Project

General

Profile

Task #638

Doxygen support

Added by Teemu Murtola over 9 years ago. Updated over 6 years ago.

Status:
Closed
Priority:
Low
Assignee:
Category:
documentation
Target version:
Difficulty:
uncategorized
Close

Description

Add code to CMake to generate an input file for Doxygen to generate documentation from the new source tree organization. Most of the code developed for trajectory analysis framework already contains Doxygen comments.


Related issues

Related to GROMACS - Task #662: Reformat existing Doxygen commentsClosed01/12/2011
Related to GROMACS - Task #867: Update Doxygen documentation for C++ codeIn Progress

Associated revisions

Revision 1e6747a9 (diff)
Added by Teemu Murtola over 9 years ago

Added basic Doxygen support for CMake.

Doxyfile is generated at the root of the binary directory, and set up
such that documentation is generated under doxygen-doc/html/.

IssueID #638

Revision fed27b73 (diff)
Added by Teemu Murtola over 9 years ago

Added Doxygen support for limited documentation.

In addition to a basic Doxyfile that generates all Doxygen
documentation, two other files, Doxyfile-lib and Doxyfile-user are now
generated by CMake for producing limited sets of Doxygen documentation
that exclude intramodule symbols (-lib) or only public API symbols
(-user).

IssueID #638

Revision 9ecf2f43 (diff)
Added by Teemu Murtola almost 9 years ago

Misc. Doxygen improvements.

- Excluded src/external/ from Doxygen documentation.
- Made inherited members appear in class documentation. Makes API
documentation easier to read if there are many public members
inherited from base classes.
- Added conditional sections for Doxygen that can be used in addition to
\internal and \libinternal.
- Consolidated use of \internal and \libinternal in file comments:
all installed (=public API) headers now produce some documentation for
the public API, even if the file only contains declarations that are
not directly in the public API.
- Added short file documentation for a few files where it was missing.

Gromacs wiki has also been updated with the changes.

Related to IssueIDs #638 and #662.

Change-Id: I9ffb9d68752697b5b58a3cc4ae45d802e32cf45c

Revision 3a09be42 (diff)
Added by Teemu Murtola almost 9 years ago

Removed unnecessary information from user API docs.

There are likely other places where \if or \cond Doxygen constructs
would be useful, but this is a start. More can be added when
documentation is further updated.

Related to IssueIDs #638 and #662.

Change-Id: I64eeee0724abb5030825f39da96313ac45cdf10b

Revision 82c93ee9 (diff)
Added by Teemu Murtola about 8 years ago

Reorganize Doxygen build.

- All doxygen-related cmake code and input files are now under
doxygen/.
- Renamed the unsuffixed Doxyfile to Doxyfile-full for consistency, and
renamed the output directory and custom target as well.
- Added a target to build all three types of doxygen documentation in
one go.
- Added an index.html file as a starting point for browsing all three
levels of documentation.

Related to #638.

Change-Id: Ia977c1aa93c55f152a15e560a60c8a1323e5d3f8

Revision 6c295b28 (diff)
Added by Teemu Murtola about 8 years ago

Improve Doxygen output layout.

- Move detailed description to the top. Mainly wanted to do this for
modules (because the member lists can be quite long, and the
description is the most interesting part), but did it for other
entities as well for consistency.
- Move the file list to the end of the module documentation because it
takes so much space.
- Removed namespace documentation from file docs, since there aren't
that many namespaces, so it doesn't make sense to repeat their
documentation for each file.
- Rename the "Related Pages" tab to "Other Docs" and move it after the
"Modules" tab.

Related to #638.

Change-Id: Iefccac61d611be9d7a13dfef4df29781e3b54cca

Revision 70a4cc9e (diff)
Added by Teemu Murtola almost 8 years ago

Extract Doxygen docs for anonymous namespaces.

With this, no Doxygen documentation in the source should get ignored.

Also added documentation for anonymous namespace members that were
causing warnings.

Related to #638.

Change-Id: I31af809272123fbc7f77ea9d3b186eddb07935bb

Revision 06069731 (diff)
Added by Teemu Murtola almost 8 years ago

Script for analyzing include dependencies.

Add a Python script plus some CMake code to run it that analyzes include
file dependencies. The script can also generate different kinds of
include dependency graphs (this implementation dates from a time when
some versions of Doxygen didn't do this properly, and the script still
has some features that Doxygen doesn't have). Some parts of the script
contain hard-coded stuff related to the Gromacs source tree layout or
the Doxygen guidelines, but the core dependency analysis should be quite
general.

There is a lot to improve in the script (in addition to missing
features, docstrings and comments are sparse, and some parts could be
better structured), but it is already usable.

Fix a few issues that produce multiple warnings from the script, and one
issue found by the script (in helpformat.h).

Related to #638 and #907.

Change-Id: I22a6d6c0818f21c828f1e7d6beb1fdada39273d2

History

#1 Updated by Teemu Murtola over 9 years ago

  • Status changed from New to In Progress

Basic support is now there, but it would be useful to have several different configuration files generated automatically for different levels of Doxygen documentation: one with everything, one with intra-module symbols excluded, and one with only public API functions documented. Leaving open for now.

One thing that I did not manage to get working was correct cross-linking of header files included like
#include "gromacs/module/header.h"
from source files. Could be a bug/limitation in Doxygen, but could be worth investigating a bit more.

The current configuration excludes non-bonded kernels from the documentation except for the C ones, because there is probably not much added value in generating ~70 MB of documentation for such highly repetitious code...

Improving the documentation itself and getting rid of most of the warnings now generated by Doxygen should go under a separate task.

#2 Updated by Mark Abraham over 9 years ago

Teemu Murtola wrote:

The current configuration excludes non-bonded kernels from the documentation except for the C ones, because there is probably not much added value in generating ~70 MB of documentation for such highly repetitious code...

Agreed, but there should be at least a stub for each architecture type, for general documentation describing design philosophy, things that didn't run fast, etc.

#3 Updated by Teemu Murtola over 9 years ago

  • Priority changed from Normal to Low
  • % Done changed from 0 to 70

The Doxygen input files for different kinds of documentation are now in, and should produce something reasonable for the analysis framework. A bigger task is to clean up existing Doxygen comments to produce reasonable documentation (and to think about issues like the one Mark raised), but I'll create a separate task for that.

I'm leaving this task still as open, because I have some Python scripts that I've used for creating include and dependency graphs between files and modules (in a format that can directly be included in Doxygen), and those might be useful to include in the documentation build process as well after some tuning. Setting the priority to low, because those scripts should not be very important right now.

#4 Updated by Teemu Murtola almost 8 years ago

  • Status changed from In Progress to Closed
  • Target version set to 5.0
  • % Done changed from 70 to 100

Can probably be closed now that also the mentioned Python script is included in git (although not very well integrated into anything), and the Doxygen input files are also fine-tuned to a reasonable extent. Some improvement is of course always possible, but can be done without a dedicated Redmine issue.

#5 Updated by Teemu Murtola over 6 years ago

  • Project changed from Source code reorganization to GROMACS
  • Category set to documentation

Also available in: Atom PDF