Date: Sun, 24 Jan 93 13:07:55 -0700 From: jan kok To: djgpp AT sun DOT soe DOT clarkson DOT edu Subject: Re: Documents... 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