Re: New docs outline

[Rich Felker <dalias@aerifal.cx>]

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