Doxygen and bfd code

Doxygen and bfd code

[Jeff Bailey]

Hi!  I'm trying to track down a bug in the elf64-hppa bfd code and want
to go through and make doxygen-style notes so I can I record what I'm
learning along as the way.  Would these be accepted upstream (subject to
accuracy, grammar, etc.)?

If you're not familiar with doxygen, here's some sample output for
marked up code with comments and such:

http://www.raspberryginger.com/jbailey/minix/html/servers_2pm_2exec_8c.html

The notation in the source code looks somewhat like JavaDoc, so it's
noticeable, but doesn't tend to get in the way too much.

Tks,
Jeff Bailey

-- 
Although when you're in the situation that RMS is telling you that
you're being too ideological about freedom, maybe, just maybe, it's
true.
- Matthew Wilcox

RE: Doxygen and bfd code

[Dave Korn]

On 08 October 2006 13:59, Jeff Bailey wrote:

> Hi!  I'm trying to track down a bug in the elf64-hppa bfd code and want
> to go through and make doxygen-style notes so I can I record what I'm
> learning along as the way.  Would these be accepted upstream (subject to
> accuracy, grammar, etc.)?
> 
> If you're not familiar with doxygen, here's some sample output for
> marked up code with comments and such:
> 
> http://www.raspberryginger.com/jbailey/minix/html/servers_2pm_2exec_8c.html
> 
> The notation in the source code looks somewhat like JavaDoc, so it's
> noticeable, but doesn't tend to get in the way too much.

  I don't have the authority to approve or deny contributions, but I think
it's very unlikely to be of any use, and hence unlikely to be accepted.

  BFD already has its own standard for internal documentation.  You should
follow that.  Adding doxygen comments would have the twin disadvantages of
requiring a new tool as part of the build process, and generating two separate
and incomplete subsets of documentation in two incompatible formats.  Take a
look at bfd.c; all those comments with instructions like 'SECTION',
'SUBSECTION', 'FUNCTION' etc. are pulled together during the build process and
used to compile the bfd internals manual.

  Having said all that, if you don't want to learn a new documentation format
and just decide to do your notes in doxygen anyway, it still might be a useful
resource for people getting to grips with bfd if you published it on your
website somewhere.  And it's up to the hppa maintainer to have the final say;
like you say, it wouldn't actually get in the way seriously.


    cheers,
      DaveK
-- 
Can't think of a witty .sigline today....

RE: Doxygen and bfd code

[Jeff Bailey]

[-- Attachment #1: Type: text/plain, Size: 957 bytes --]

Le dimanche 08 octobre 2006 à 15:14 +0100, Dave Korn a écrit :

>   BFD already has its own standard for internal documentation.  You should
> follow that.  Adding doxygen comments would have the twin disadvantages of
> requiring a new tool as part of the build process, and generating two separate
> and incomplete subsets of documentation in two incompatible formats.  Take a
> look at bfd.c; all those comments with instructions like 'SECTION',
> 'SUBSECTION', 'FUNCTION' etc. are pulled together during the build process and
> used to compile the bfd internals manual.

Ah cool.  I haven't looked at the bfd manual in years, but if there's an
existing format I can document in, that should be good enough.

I'll go digging and see what I can add.

Tks,
Jeff Bailey

-- 
Although when you're in the situation that RMS is telling you that
you're being too ideological about freedom, maybe, just maybe, it's
true.
- Matthew Wilcox

[-- Attachment #2: Ceci est une partie de message numériquement signée --]
[-- Type: application/pgp-signature, Size: 189 bytes --]