next up previous contents
Next: Justification Up: Proposed Changes for CXX2HTML Previous: Introduction

Summary of changes

The following points summarize the changes we propose for Cxx2html:

  1. 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.
  2. All class and summary files should have the following AIPS++ specific information:
    1. pointer to AIPS++ programmer manual
    2. pointer to package document (when we get one)
    3. pointer to module document
    4. include path ;SPMlt;package/module/file.h;SPMgt;
    5. copyright notice
    6. pointer to bug reporting system
    7. date and how it was generated.
  3. The header summary files should contain:
    1. List of classes
    2. Global Enums
    3. Global Typedefs
    4. Global Functions
    5. Class summaries
      1. Public Enums
      2. Public Typedefs
      3. Public Functions (including inherited functions)
      4. Protected Enums
      5. Protected Typedefs
      6. Protected Functions (including inherited functions)
      7. Public Data
      8. Protected Data
      9. Optional Private Enums
      10. Optional Private Typedefs
      11. Optional Private Functions (including inherited functions)
  4. Formatting changes to summary listing; function names are aligned with return types right justified.
  5. The class description files should contain:
    1. only one class per file
    2. Standard header descriptions
    3. Functions descriptions in the order specified by summary file. No need for inherited functions though.
    4. 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.
  6. 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.)
  7. Formatting changes to member descriptions; argument types are aligned with one argument per line, also horizontal lines separate the functions.
  8. The current module documentation will need some revision. Discussion of those revisions is beyond the scope of this document.
  9. The "project" level document would tie in all module documentation. Discussions of the project document are also beyond the scope of this document.

next up previous contents
Next: Justification Up: Proposed Changes for CXX2HTML Previous: Introduction

tcornwel@nrao.edu