[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