Next: Justification
Up: Proposed Changes for CXX2HTML
Previous: Introduction
The following points summarize the changes we propose for Cxx2html:
- Each header file should produce a summary file of each class. Individual files containing the full description should be
created for each class. We suggest the following naming convention, file-summary.html for the summary file, file-class.html for
the full class description.
We propose private enums, typedefs, and functions be made available via a switch on cxx2html. The default
setting of the "private" switch would be off.
- All class and summary files should have the following AIPS++ specific
information:
- pointer to AIPS++ programmer manual
- pointer to package document (when we get one)
- pointer to module document
- include path ;SPMlt;package/module/file.h;SPMgt;
- copyright notice
- pointer to bug reporting system
- date and how it was generated.
- The header summary files should contain:
- List of classes
- Global Enums
- Global Typedefs
- Global Functions
- Class summaries
- Public Enums
- Public Typedefs
- Public Functions (including inherited functions)
- Protected Enums
- Protected Typedefs
- Protected Functions (including inherited functions)
- Public Data
- Protected Data
- Optional Private Enums
- Optional Private Typedefs
- Optional Private Functions (including inherited functions)
- Formatting changes to summary listing; function names are aligned with return types right justified.
- The class description files should contain:
- only one class per file
- Standard header descriptions
- Functions descriptions in the order specified by summary file.
No need for inherited functions though.
- Global functions are put at the end of the class file. If there are multiple classes, global functions should
be put in the appropriate active class.
- Functions maybe grouped and the group named. Groups may be nested. Groups should be identified with a label and
indentation scheme. Nested groups in the summary file could be identified with a label that prepends the parent group(s).
(We don't feel very strongly about nested groups but, believe cxx2html should support nested groups at sometime.
An example, not from AIPS++ code, may be found in
http://tarzan.aoc.nrao.edu/~wyoung/protopages/nestedgroups.html.)
- Formatting changes to member descriptions; argument types are aligned with one argument per line, also horizontal
lines separate the functions.
- The current module documentation will need some revision. Discussion of those revisions is beyond the scope of this
document.
- The "project" level document would tie in all module documentation. Discussions of the project document are also
beyond the scope of this document.
Next: Justification
Up: Proposed Changes for CXX2HTML
Previous: Introduction
tcornwel@nrao.edu