Re: [PATCH] Turn on more documentation

[Noah Lavine]

Replying to myself, I've attached two more patches, which document two
more modules.

The approach I've been taking is to take the comments that modules
already have and convert them to the documentation format that
(texinfo reflection) understands. If people agree that this is a good
approach, there are a few more modules I can convert easily, but I'd
like to check that we want to use this approach before doing a lot of
work and getting out of sync with the main repository.

I can say more about the tradeoffs if anyone is interested, but I
think this is the right choice because we can use it right now. Other
options would give prettier documentation, but would be more work.

Noah

On Wed, May 2, 2012 at 11:20 PM, Noah Lavine <address@hidden> wrote:
> Hello all,
>
> As part of my investigation into modules that don't have
> documentation, I discovered that several modules in ice-9/ actually
> have usable documentation that we are just not using in our build
> process. (For reference, everything in the "Standard Library" section
> of the manual is snarfed from .scm source files.) This patch makes
> Guile build documentation for (ice-9 binary-ports), (ice-9
> common-list), (ice-9 documentation), (ice-9 gap-buffer), (ice-9 runq),
> (ice-9 serialize), and (ice-9 time). It gets incorporated into the
> manual as part of the "Standard Library" section.
>
> This seems like an easy way to get documentation for a few more
> modules. What do you think?
>
> (You may have to do "rm doc/ref/standard-library.texi && rm
> doc/ref/guile.info*" in order to build with the change. The makefile
> doesn't know about all of the dependencies that it should.)
>
> I also discovered while working on this that several modules have
> in-line commentary and also hand-written texinfo pages. The list is
> expect.scm, ftw.scm, futures.scm, getopt-long.scm, i18n.scm,
> optargs.scm, q.scm, regex.scm, threads.scm, and vlist.scm. Was there a
> reason for this? Perhaps the inline documentation format isn't as
> flexible as writing it by hand?
>
> Thanks,
> Noah

0001-Document-ice-9-and-let-star.patch
Description: Binary data

0002-Document-ice-9-calling.patch
Description: Binary data