[Doxygen-develop] several suggestions

[Ilya S. <ily...@MI...>]

Here is my "wish list" for Doxygen:

1. Support documenting "aspects" i.e. scattered code fragments that implement one functionality,
with the following simple changes:
    -- when the name of a module is mentioned in the comments (any comments -- including comments
    inside function code), in the doxygen-generated source listing make the module name 
    a hyperlink to the module documentation page
    -- on the module documentation page, add a list of source lines on which the module is mentioned,
    making each line a hyperlink to the corresponding line in the source listing generated by doxygen.

Then, in the doxygen-generated source listing, it's easy to find all code implementing a given functionality,
and it's easy to jump from a code chunk to all related chunks (via the module page).

2. Generate more automatic links from the source code listings -- any mention of a documented entity,
including in the comments other than the special comment blocks, can be linked to the documentation page for that entity
or to the definition of the entity in the source code.
And from the documentation page can link to the list of source lines on which the entity is used.

3. Allow placing named "anchors" in comments (in any comments -- not just in the special comment blocks), which can
then be referenced from the special comment blocks.  The reference generates a link to the source line containing
the anchor, in the doxygen-generated source listing.

4. Add brief descriptions to all generated pages -- e.g. on the "Data fields", the "Globals" pages etc. put the
brief description of each entity to the right of the name (truncated as needed).  Also when showing the parents
of a class as a DOT diagram, to the right of each parent class put a brief description.

5. Be able to document a directory -- right now the only way is to create a module and put all the files in the directory
into the module.  In Java, documenting packages takes care of this; but C doesn't have packages.

6. Be able to document "function outlines" -- inside function code, have stylized comments that can indicate outline levels;
when generating source listings, have a "function outline" page with two frames, one showing the outline items and the other
showing the source code; clicking on an outline item brings the corresponding source code line into view.

7. Incremental updating of documentation: only parse those files that have later modification dates than the corresponding
documentation files.  This can be implemented on top of the existing "tag file" functionality: have a tag file for each
source file, and re-generate only those tag files that are older than the corresponding source files.