This is the mail archive of the guile@cygnus.com mailing list for the guile project.
| Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
|---|---|---|
| Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
>>>> In message <wwn7m1g46uh.fsf@totoro.red-bean.com> >>>> Sent on 14 Jul 1998 14:37:10 -0400 >>>> Honorable Jim Blandy <jimb@red-bean.com> writes >>>> on the subject of "generating a manual from annotations in source code": >> Do people feel that, if the documentation is a separate file, >> programmers will be discouraged from writing docs, whereas, if the >> documentation were mingled with the source, then programmers would >> naturally write docstrings as they go along? Manual is manual and docstrings are docstrings. Both are necessary, and one cannot replace or autogenerate the other. The manual can include the docstrings though, e.g., as hypertext links whenever a function or a variable is mentioned (a la CLHS), but, again, this doesn't replace a coherent, purposefully written and thoroughly designed (yep, `designed'!) manual. IMHO, docstrings should be written and modified along with the code, should be kept there until the compile time, and then extracted and placed in a in a special location convenient for run-time documentation extraction (Emacs model). The larger, conceptual issues should be addressed in a separate manual, which can refer to the docstrings for formal details, while providing examples and explanations. Just my $0.02... -- Sam Steingold, running RedHat5.1 GNU/Linux (http://www.linux.org) Micros**t is not the answer. Micros**t is a question, and the answer is Linux, the choice of the GNU (http://www.gnu.org) generation. The software said it requires Windows 3.1 or better, so I installed Linux.