New docs outline

New docs outline

[Rich Felker]

This is just a rough draft of an outline for the nice documentation
I'd eventually like to have for musl. Sending it to the list as a way
to make sure it doesn't get forgotten, and as a way of bouncing around
ideas on it..

1. Introduction and scope
2. Conformance statements
3. Supported systems
4. Build and installation
5. Installed components
   A. Dynamic linking runtime
   B. Development files
6. Filesystem layout dependencies
   ... required and optional directories/devices/mounts/files ....
7. Basic (developer) usage information.
8. Implementation-defined behavior
9. Further documented behavior guarantees
10. Coding style
11. Source tree layout
12. Implementation internals (malloc, pthread, stdio, etc.)
13. Porting

Re: New docs outline

[nwmcsween]

I would really like a set coding style, currently musl utilizes whatever whomever decided to write at the time, usually for pedantic things such as parens around sizeof, spacing around operators, etc. I also wouldn't mind Linux style function documentation.

On Nov 15, 2012, at 2:20 PM, Rich Felker <dalias@aerifal.cx> wrote:

> This is just a rough draft of an outline for the nice documentation
> I'd eventually like to have for musl. Sending it to the list as a way
> to make sure it doesn't get forgotten, and as a way of bouncing around
> ideas on it..
> 
> 1. Introduction and scope
> 2. Conformance statements
> 3. Supported systems
> 4. Build and installation
> 5. Installed components
>   A. Dynamic linking runtime
>   B. Development files
> 6. Filesystem layout dependencies
>   ... required and optional directories/devices/mounts/files ....
> 7. Basic (developer) usage information.
> 8. Implementation-defined behavior
> 9. Further documented behavior guarantees
> 10. Coding style
> 11. Source tree layout
> 12. Implementation internals (malloc, pthread, stdio, etc.)
> 13. Porting

Re: New docs outline

[Rich Felker]

On Thu, Nov 15, 2012 at 02:38:37PM -0800, nwmcsween@gmail.com wrote:
> I would really like a set coding style, currently musl utilizes
> whatever whomever decided to write at the time, usually for pedantic
> things such as parens around sizeof, spacing around operators, etc.

For sizeof, the style is not to use parens on objects, only on types
or expressions where the parens are needed for grouping. This makes it
clear that the size of an object, rather than a type, is being taken.
I believe this is consistent across the source except for some code
like TRE or crypt stuff that was originally written elsewhere and
imported into musl; it was at least intended to be consistent.

For spacing and parens on operators, it's usually done just from a
standpoint of readability -- avoiding too many levels of parens, and
using spacing to help make the grouping obvious. Also to avoid going
past 80 columns or breaking lines (which also hurts readability).

Personally, I feel like this sort of goal/effect-oriented style
guideline is more useful than a strict formatting rule. The latter can
easily be obtained by a machine if desired, but often hurts
readability as much as it helps.

> I also wouldn't mind Linux style function documentation.

I'm not familiar with the convention, but it might be worth adopting.
However, musl doesn't have many functions which are internal-use-only.
Most things are standard interfaces documented in the C or POSIX
standards.

Rich