header layout agreements

[Christian Neumair]

As the topic suggests this thread focusses on the layout of our existing
wine header code. Maybe it sounds a bit pedantic but it's essential to
have unified guidelines all developers should follow:

Dimitrie O. Paun  already did a great job [1]:
He just added additional comments to a common header describing exactly
what still remains to do.
We should have a unified header which contains at least:

/*
 * ...
 * ####### HEADER (normally license terms) ########
 *
 * DESC
 *   This DLL manages <...>
 *
 * FUNC
 *   -- 1st function
 *         Internal FAN flags:
 *         FAN_TASY - specifies our imaginary code
 *         FAN_TASTIC - this array stores some code (not yet
 *                      implemented) 
 *   -- 2nd function
 *   -- 3rd function (not yet implemented)
 *   -- etc.
(*
 * Optional :
 *
 * TODO
 *  -- 1st function: implement FAN_TASTIC.
 *  -- yet another item
 *
 * BUGS
 *  -- 1st function: we need to handle a call without FAN_TASY being
 *     passed
 *  -- plain old item
 */)

We're already providing detailed information on parameters, return
values etc. above many functions so adding this to the file header
would just bloat it.
Comments on that, please :)

regs,
 Chris

[1] http://www.winehq.com/hypermail/wine-patches/2002/10/0343.html

[Dimitrie O. Paun]

On November 1, 2002 07:12 am, Christian Neumair wrote:
> Comments on that, please :)

Well, here it goes:
  -- I don't care much about DESC. In fact, it should be
     painfully obvious what the file is for in 99.99% of
     the cases. If you feel like adding it, sure, go ahead,
     you can add a small blurb, without the DESC tag. It's
     clear what it does, or the description is b0rken :)
  -- I don't think FUNC section is a good idea. It server
     no purpose (almost all we do is documented by MS, just
     go read that docu), and besides, can be automatically
     extracted from the source. I think we should add the
     *absolute* minumum docs, and not more: this way people
     will actually add the essential things, easier to
     maintain, less chance of bitrot. This one fails the test.
  -- The TODO & BUGS sections are very useful (I mean, more
     than words can say), assuming they define a close universe.
     That is, they document all that's left to do, so I don't
     have to go understand all code to figure this out.
     This is where people with good domain knowledge should
     do a quick brian dump. It's not much work, and it helps
     other developers plenty. A good way to keep track of
     progress, and status, BTW.

[Francois Gouget]

On 1 Nov 2002, Christian Neumair wrote:
[...]
> - FUNC
> - -- 1st function
> -
>     Internal FAN flags:
> -
>     FAN_TASY - specifies our imaginary code
> -
>     FAN_TASTIC - this array stores some code (not yet
> -
>                  implemented)
> - -- 2nd function
> - -- 3rd function (not yet implemented)
> - -- etc.

I pretty much agree with Dimitrie. I will just add that any
documentation related to a function should be located in or near that
function, not at the top of the file, miles away from it.

Also, if it's in a machine extractable form, so much the better.