[cfe-dev] Notes on Doxygen documentation style

Chris Lattner clattner at apple.com
Tue Jan 20 14:13:24 PST 2009


On Jan 20, 2009, at 9:46 AM, Douglas Gregor wrote:

> I'm a documentation nut, and there are some places in Clang's internal
> documentation that I think we can do even better. Here are some
> comments on the subject.

Hey Doug,

I agree that this is great to do and makes the doxygen output very  
nice.  There is a tender balance between getting people to document  
stuff at all and making the documentation truly beautiful, but I agree  
that very common/popular APIs should be well documented.

> Architectural Descriptions
> ====================
>
> We currently have a Clang "internals" manual, with documentation about
> various subsystems within Clang:
>
>   http://clang.llvm.org/docs/InternalsManual.html
>
> We could consider bringing this documentation in with the rest of the
> Doxygen documentation using, e.g., Doxygen's \page and \newpage
> markup. The benefit of bringing all of the internals documentation
> into Doxygen is that we can more easily cross-link between specific
> function/class documentation and the more general, architectural
> information.

This is one thing that I don't agree with.  I think it is fine to link  
from the internals manual to the doxygen (we do this in other LLVM  
dox) just using normal links.  "Hiding" the documentation in the code  
makes it harder to find IMO.

-Chris



More information about the cfe-dev mailing list