| Deletions are marked like this. | Additions are marked like this. |
| Line 66: | Line 66: |
| header could/should contain: |
The stub file header supporting Doxygen, used in the freesurfer code base, and the contents of which are found in dev/doxy-file-header, is this: {{{ /** * @file REPLACE_WITH_FILENAME * @brief REPLACE_WITH_ONE_LINE_SHORT_DESCRIPTION * * REPLACE_WITH_LONG_DESCRIPTION_OR_REFERENCE */ /* * Original Author: REPLACE_WITH_FULL_NAME_OF_CREATING_AUTHOR * CVS Revision Info: * $Author: nicks $ * $Date: 2008/03/03 22:25:29 $ * $Revision: 1.8 $ * * Copyright (C) 2002-2008, * The General Hospital Corporation (Boston, MA). * All rights reserved. * * Distribution, usage and copying of this software is covered under the * terms found in the License Agreement file named 'COPYING' found in the * FreeSurfer source code root directory, and duplicated here: * https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferOpenSourceLicense * * General inquiries: freesurfer@nmr.mgh.harvard.edu * Bug reports: analysis-bugs@nmr.mgh.harvard.edu * */ }}} |
| Line 68: | Line 96: |
|
* filename * module (see next section) * brief description * original author, or file owner (to contact in case of need for major changes) * last edit author * open-source license blrub with link * ? * ? |
The all-caps REPLACE_WITH... items should be updated when this header is included at the top of a source file. The first section is read by Doxygen. @brief is the one-line summary, and the REPLACE_WITH_LONG_DESCRIPTION_OR_REFERENCE line can be multiple lines describing the file in detail, or at least include a reference to a paper describing the techniques used, if applicable. The second section (the author name, CVS info and copyright message) is not read by Doxygen. |
Doxygen
Basics
This page is for notes on using Doxygen to document the Freesurfer source code.
Doxygen, http://www.stack.nl/~dimitri/doxygen/index.html, is a documentation system for C++, C, Java, and some other weird languages. It can generate html docs documenting a projects source code, by either extracting special tags from the source code (put there by people wanting to make use of doxygen), or doxygen attempts to build documentation from existing source.
Doxygen seems to be installed on the NMR systems, type:
doxygen --version
Step 1 in using doxygen is the creation of a config file. A default is created by typing:
doxygen -g
which creates a file called Doxygen.
For Freesurfer, a config file called Doxygen has been created and commited to CVS, and appears at the root directory after a CVS update.
The defaults that have been changed are the following:
20c20 < PROJECT_NAME = FreeSurfer --- > PROJECT_NAME = 33c33 < OUTPUT_DIRECTORY = ./doxygen --- > OUTPUT_DIRECTORY = 189c189 < OPTIMIZE_OUTPUT_FOR_C = YES --- > OPTIMIZE_OUTPUT_FOR_C = NO 462c462 < INPUT = utils --- > INPUT = 471c471 < FILE_PATTERNS = *.c *.cpp *.h --- > FILE_PATTERNS = 477c477 < RECURSIVE = YES --- > RECURSIVE = NO 489c489 < EXCLUDE_SYMLINKS = YES --- > EXCLUDE_SYMLINKS = NO
These changes are preliminary. Notice just the utils directory is marked to be processed. Because virtually none of the freesurfer source files have any doxygen tags, the html output produced by doxygen is mostly useless junk, or missing vast numbers of file.
To generate the html and latex docs, where $FSDEV is your CVS dev dir, type:
cd $FSDEV doxygen
The docs are put in the ./doxygen directory. See ./doxygen/html/index.html
Default file header
The stub file header supporting Doxygen, used in the freesurfer code base, and the contents of which are found in dev/doxy-file-header, is this:
/** * @file REPLACE_WITH_FILENAME * @brief REPLACE_WITH_ONE_LINE_SHORT_DESCRIPTION * * REPLACE_WITH_LONG_DESCRIPTION_OR_REFERENCE */ /* * Original Author: REPLACE_WITH_FULL_NAME_OF_CREATING_AUTHOR * CVS Revision Info: * $Author: nicks $ * $Date: 2008/03/03 22:25:29 $ * $Revision: 1.8 $ * * Copyright (C) 2002-2008, * The General Hospital Corporation (Boston, MA). * All rights reserved. * * Distribution, usage and copying of this software is covered under the * terms found in the License Agreement file named 'COPYING' found in the * FreeSurfer source code root directory, and duplicated here: * https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferOpenSourceLicense * * General inquiries: freesurfer@nmr.mgh.harvard.edu * Bug reports: analysis-bugs@nmr.mgh.harvard.edu * */
The all-caps REPLACE_WITH... items should be updated when this header is included at the top of a source file. The first section is read by Doxygen. @brief is the one-line summary, and the REPLACE_WITH_LONG_DESCRIPTION_OR_REFERENCE line can be multiple lines describing the file in detail, or at least include a reference to a paper describing the techniques used, if applicable.
The second section (the author name, CVS info and copyright message) is not read by Doxygen.
Modules
doxygen supports grouping things together: http://www.stack.nl/~dimitri/doxygen/grouping.html
what modules should be created for freesurfer? group by utility type? ie volume, surface, display
Comments and Suggestions
- Doesnt seem to allow documenting csh scripts
What special commands, http://www.stack.nl/~dimitri/doxygen/commands.html, are useful?
- \file
- \addtogroup
- Support for open-source community: example of well-documented source (using doxygen) that community can follow if they want to document the source (not making code changes)
- best approach is probably to build one file at a time, not try to 'auto-document' the whole code-base (resulting in useless documentation). start with, say, utils.h and the mri struct.
Status
- 8 March 2006 - the next step is to devise a basic header, and also to create a config file that generates docs for a few core files, with the intent to add files to be 'doygenated' as they are completed.