libstdc++-v3/docs/doxygen/TODO

   1
   2 The approach I've been using for a given header is to recursively do each
   3 of the "bits" headers which make up the standard header.  So, e.g., while
   4 there are four headers making up <algorithm>, three of them were already
   5 documented in the course of doing other headers.
   6
   7 "Untouched" means I've deliberately skipped it for various reasons, or
   8 haven't gotten to it yet.  It /will/ be done (by somebody, eventually.)
   9
  10
  11  Area           Still needs to be doxygen-documented
  12 -----------------------------------------------------------
  13
  14 c17             FINISHED (Nothing in Clause 17 "exists" in terms of code.)
  15 c18             <limits>, Note A
  16 c19             Note A
  17 c20             Note A
  18 c21             Untouched, Note B
  19 c22             Untouched
  20 c23             See doxygroups.cc and Note B.
  21 c24             Untouched
  22 c25             stl_algo.h (lots of stuff)
  23 c26             <complex>, <valarray>, stl_numeric.h[26.4], Note A
  24 c27             Untouched
  25
  26 backward/       Not scanned by doxygen.  Should it be?
  27
  28 ext/            Some of the SGI algorithm/functional extensions.
  29                 All of rope/hashing/slist need docs.
  30
  31 __gnu_cxx       Tricky.
  32
  33 [1.3.5]         "implementation-defined behavior:  behavior ... that depends
  34                 on the implementation *and that each implementation shall
  35                 document*."  [my emphasis]  Not all implementation choices
  36                 have been thus described; doxygen is not necessarily the
  37                 appropriate place for such descriptions, either.
  38
  39 -----------------------------------------------------------
  40
  41 NOTES:
  42
  43 A)  So far I have not tried to document any of the <c*> headers.  So entities
  44 such as atexit() are undocumented throughout the library.  Since we usually
  45 do not have the C code (to which the doxygen comments would be attached),
  46 this would need to be done in entirely separate files, a la doxygroups.cc.
  47
  48 B)  Huge chunks of containers and strings are described in common "Tables"
  49 in the standard.  How to reproduce this information?
  50
  51
  52
  53 STYLE:
  54 stl_deque.h, stl_pair.h, and stl_algobase.h have good examples of what I've
  55 been using for class, namespace-scope, and function documentation, respectively.
  56 These should serve as starting points.  /Please/ maintain the inter-word and
  57 inter-sentence spacing, as this might be generated and/or scanned in the
  58 future.
  59
  60
  61 vim:ts=4:et: