Doxygen Documentation Is Lacking

[llvmbot]

Bugzilla Link	778
Resolution	LATER
Resolved on	Mar 06, 2010 14:00
Version	trunk
OS	All
Reporter	LLVM Bugzilla Contributor
CC	@lattner

Extended Description

Currently, there is only partial support for doxygen documentation in the public
header files. The following improvements are requested:

1. Move "file level" comments that actually describe a class to be associated
   with the class so doxygen user's don't have to dig for it and so doxygen doesn't
   ignore it.

2. Group class members into sections of related functionality so that the those
   groups are expressed in the documentation. This makes it much easier to find the
   appropriate methods because entire groups can be quickly ignored if they are
   off-topic for the reader's intention.

3. Resolve the @​brief issue (the @​brief keyword shows up in the output)

4. Get a non-blank main page (introduction) so that people can get a basic idea
   of what it is they're reading about.

[llvmbot]

Mine

[lattner]

Is this one done? Is there something specific that can be done, or is this an ongoing issue that don't
warrant a bugzilla?

[llvmbot]

Its kinda both. At the very least the .h files need to be fully documented.
There are still many functions with either missing or incorrect (doxygen wise)
documentation markup. This is one of those low priority things that I try to
work on when I can.

I'd like to leave this open and see if I can get to it for 2.0. If it doesn't
happen by then, we can close it. But, I need the reminder on my bug list.

[llvmbot]

There are several other things needing to be done to:

1. Turn on scavenging of .cpp files not just .h files (if it isn't already).
2. Make sure that every class and every public method of every class in the
   llvm/include/llvm directory hierarchy has a comment.
3. Check consistency between header comments and actual functionality. Things
   change over time and comments get stale.

However, all of this bug's requests comes under the realm of "continuous
improvement". Consequently, we're closing it.

The items here are taken as a personal "to do" item for Reid and it is
recommended that all developers pitch in to aid in this effort.