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 If you document an area and need to skip (for whatever reason) a non-trivial
  11 entity (i.e., one that should be documented), go ahead and add the comment
  12 markup, and use the homegrown @doctodo tag.  See include/bits/stl_iterator.h
  13 for examples of this.  Doing so will at least cause doxygen to consider the
  14 entitiy as documented and include it in the output.  It will also add the
  15 entity to the generated TODO page.
  16
  17
  18  Area           Still needs to be doxygen-documented
  19 -----------------------------------------------------------
  20
  21 c17             FINISHED (Nothing in Clause 17 "exists" in terms of code.)
  22 c18             <limits>, Note A
  23 c19             Note A
  24 c20             Note A
  25 c21             Untouched, Note B
  26 c22             Untouched
  27 c23             See doxygroups.cc and Note B.  Notes on what invalidates
  28                 iterators need to be added.  std::list-specific memfns need
  29                 to be filled out.
  30 c24             stl_iterator.h (__normal_iterator, other small TODO bits)
  31                 stream iterators
  32 c25             stl_algo.h (lots of stuff)
  33 c26             <complex>, <valarray>, stl_numeric.h[26.4], Note A
  34 c27             ios_base callbacks and local storage
  35                 basic_ios::copyfmt()
  36                 std_streambuf.h's __copy_streambufs()
  37                     " "           _M_* protected memfns (data has been done)
  38                 fstream and sstream protected members
  39
  40 backward/*      Not scanned by doxygen.  Should it be?  Doubtful.
  41
  42 ext/*           Some of the SGI algorithm/functional extensions.
  43                 All of rope/hashing/slist need docs.
  44
  45 __gnu_cxx       Tricky.  Right now ext/* are in this namespace.
  46
  47 -----------------------------------------------------------
  48
  49 NOTES:
  50
  51 A)  So far I have not tried to document any of the <c*> headers.  So entities
  52 such as atexit() are undocumented throughout the library.  Since we usually
  53 do not have the C code (to which the doxygen comments would be attached),
  54 this would need to be done in entirely separate files, a la doxygroups.cc.
  55
  56 B)  Huge chunks of containers and strings are described in common "Tables"
  57 in the standard.  These are pseudo-duplicated in tables.html.  We can
  58 use doxygen hooks like @pre and @see to reference the tables.  Then the
  59 individual classes do like the standard does, and only document members for
  60 which additional info is available.
  61
  62
  63 STYLE:
  64 stl_deque.h, stl_pair.h, and stl_algobase.h have good examples of what I've
  65 been using for class, namespace-scope, and function documentation, respectively.
  66 These should serve as starting points.  /Please/ maintain the inter-word and
  67 inter-sentence spacing, as this might be generated and/or scanned in the
  68 future.
  69
  70
  71 vim:ts=4:et: