Notes on Doxygen documentation style

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.

Coverage

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

Hi Chris,

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.

This is ok, as long url mangling doesn't change between Doxygen versions.
I am not sure, if it is case or not.
How about, putting internals manual in some lets say *.doc files,
inline html there, and adjust Doxygen's config to include those files?

Piotr

Yep, that's a reasonable concern. Let's not do this, then.

  - Doug