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] |
Jim Blandy <jimb@red-bean.com> writes: > 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? sort of but not entirely. definitely docstring-grokking support reduces the inconvenience barrier to a point where it is indeed natural to throw a few words in the source. but i don't see it as a either-or situation; having a separate file encourages conceptual and task-oriented (ugh) documentation. i prefer access to both approaches w/ docstring-grepping relegated to a reference or internals manual. other programmers i know simply avoid documentation, claiming the required skillset makes all efforts by the non-skilled ineffective and actually dangerous (eg, out-of-sync docs causing catastrophic operator error). obviously there are many views. thi