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