Mail Archives: djgpp/1993/01/24/15:57:50
alane AT wozzle DOT linet DOT org (J. Alan Eldridge) inquireth:
> So, what do you need to know (and don't say, "everything").
This is one user's view of what documentation is needed. This really applies
to ANY library.
Ordered most to least important:
1. The djgpp document that I use most is docs/funcs.doc which, for each
library, gives a one-line description of each function, showing the function
name, args, return type, and states the purpose in a few words. I think such
a document for your libs would produce the most benefit per effort expended.
(I also think it would be worthwhile to include your information in funcs.doc
so that information about all available libraries exists in one place, and so
that users can get an idea what is in your packages without having to download
the whole package).
2. A paragraph or two summarizing the libs' capabilities. Lacking this
information, I spent a hour or so downloading the window package, unpacking
it, and studying it to see whether it provided a way to buffer up old text
so that it could scrolled back. (I concluded that it didn't.)
3. What is the very minimum set of calls needed to do something useful? And
what restrictions are there on the order in which calls can be made? In some
cases this is obvious, but in some cases, e.g. scaling and viewport functions
in some graphics packages, it is not obvious how the functions interact. Demo
programs are useful, but they don't always answer the above questions.
4. In order to understand the source code, the following would be helpful:
a) An index of the files, with a couple lines of description of each.
b) A description of the relationships among the C++ classes (the function
documentation - item #1 above - might be sufficient).
c) In the source files, a comment at the beginning of each function describing
its purpose, and any other information that might not be obvious to the reader.
Cheers,
- Jan
- Raw text -