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