George Russell writes:
> "D. Tweed" wrote:
> > Documentation is a vague term: certainly it'd be undesirable for a
> > specification to the libraries to just a literate copy of the code
> > itself. But if you're thinking in terms of an open source project where
> > people fix bugs in the libraries then libraries that contain some
> > explanation would be useful (as an additional item to the library spec).
> Couldn't agree more. Every module should be commented, and every exported
> symbol (and lots of the internal ones) should also be commented. But I don't
> think you need anything more than comment characters for this.
George made a good point which I think deserves to be made explicit:
client-level documentation, i.e., documentation of the specification, and
developer-level documention, i.e., documentation of the implementation (and
possibly including the specification), have distinct requirements. I think
literate programming is most useful for documenting the implementation, the
idea being that you are more likely to track the actual state of the source if
you keep the documentation in the source itself. And, from this perspective,
my remark about using the documentation system for the Haskell
libraries---which should clearly be client-level---is wrong-headed.
As far as literate programming goes, then, we could restrict the discussion to
developer-level documentation. However, I personally would still like a de
facto system for describing specifications of libraries and APIs... Also,
although you can well argue that documentation for the specification does not
belong inside the source, the formatting system (or whatever) for client- and
developer-level documentations can profitably be shared, or one can subsume
the other.
--fa(c)
