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]

Re: Scheme documentation question


Dirk Herrmann <dirk@ida.ing.tu-bs.de> writes:

> Tel <telford@eng.uts.edu.au> wrote:
> > Is anything wrong with:
> > 
> > (document-variable VAR DOC-STRING)
> > 
> > OK, I'll admit that you must type the variable name twice
> > and you might spell it wrong the second time, but why go for
> > something complicated when something simple will work?
> > Is it necessary for one function to do everything?
> 
> I like this idea. In fact, it might even make sense to extend it to document
> functions as well, because this way you can add flexibility to the
> documentation system.

I don't like this idea at all.  From a software-enginering maintenance
and evolution perspective, we want to increase the coupling between the
code and the documentation.

> Possible extensions:
> 
> (document-variable VAR DOC-STRING 
>                    &opt CHAPTER-HIERARCHY 
>                         SEE-ALSO-LIST)
> (document-function FUNCTION DOC-STRING 
>                    &OPT PARAM-DESCRIPTION-ALIST 
>                         CHAPTER-HIERARCHY 
>                         SEE-ALSO-LIST)
> 

Ugh. Now you're repeating the signature of the procedures, too.  Very
error prone, and very bad.

> By separating functions and documentation we get added flexibility and make
> parsing and documentation extraction easier. We could even put documentation
> and code into different files (it is questionable if this is a good idea in
> general, however, in some cases it might be).

I don't see why it's so hard as it is... it's just a simple
implementation shortcoming that define on variables doesn't allow doc
strings to be included.

> It is also less intrusive to add documentation to code: You don't have to use
> define-public just to be able to add your documentation strings. Documentation
> is cleanly separated and can be provided by a module without need to include
> it in the core during startup. This seems better to me than to deeply embed
> documentation support within the very basic functions/macros like it is done
> with define-public.

These are all implementation issues -- the reader can throw away doc
strings or they can be stored in a database statically ahead of time;
we don't need to decouple the documentation from the code and variables
to get these benefits.

> By redefining the document-xxx functions, users have even more fine-grained
> control over which documentation is to be stored and which can safely be
> abandoned. This may be an issue if lots of modules are loaded and the loaded
> doc strings eat a lot of memory or additional GC time overhead.
> 
> Summarized: this way, documentation is easily and flexibly generated by
> developers, extracted by parsers and customized by guile users.

I don't buy any of these arguments.  The problems with doc strings are
all due to guile's management of the strings, not due to anything
intrinsic.  Local redundancies are bad, and only expand the possibility
for error (cf. non-local redundancies [e.g., types] which are useful for
checking).

I think we just need a define-user-variable macro (and guile needs a
define-variable macro also -- probably with public counterparts) that
expects a doc-string.  Then the guile extractor will have an easy time
getting the string, and guile can do more interesting management of the
documentation as its self-documenting system improves.

Greg