[cfe-dev] Notes on Doxygen documentation style

[Douglas Gregor]

On Jan 20, 2009, at 2:13 PM, Chris Lattner wrote:
> On Jan 20, 2009, at 9:46 AM, Douglas Gregor wrote:
>> 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.


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

	- Doug