Doxygen and bfd code
Sun Oct 8 14:14:00 GMT 2006
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:
> 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.
Can't think of a witty .sigline today....
More information about the Binutils