Docstrings and Reference manual (Re: Discussing Guile and revising interfaces)

[Keisuke Nishida <kxn30 at po dot cwru dot edu>]

Mikael Djurfeldt <mdj@mdj.nada.kth.se> writes:

> Instead of changing Guile's interface directly (for example by
> deprecating functions) we plan to systematically go through the entire
> Guile API by making annotations in the reference manual.  We would add
> notes such as "OK", "needs to change this way...", "consider ..."
> etc.  Such notes could be conditional in the manual, so that they
> wouldn't appear until you set a flag when compiling it.

This is great.  Is there a plan how to implement the reference manual?

If most part of the manual is going to be written as docstrings, I'd
like to discuss the detailed format of the docstrings.  I'm thinking
of extending the docstring format so that we can add "properties" to
each docstring.  For example, the following definition

  SCM_DEFINE_PROCEDURE (scm_foo, "foo", 1, 1, 1,
  (SCM x, SCM y, SCM z),
  "xref: bar"
  "status: experimental"
  ""
  "This is foo...")
  {
    ...
  }

may produce a database entry

  ((type . primitive-procedure)
   (name . foo)
   (required-args . (x))
   (optional-args . (y))
   (rest-arg . z)
   (xref . (bar))
   (status . experimental))
  This is foo...

and this is converted to an output of describe

  ----------------------------------------
  `foo' is a primitive procedure.

  (foo x #&optional y #&rest z)

  This is foo...

  Status:   experimental
  See Also: bar
  ----------------------------------------

or a manual entry

  ----------------------------------------
  - Primitive Procedure: foo X #&optional Y #&rest Z

    This is foo...
  ----------------------------------------

In this way, we can add any extensions to the docstrings.  One property
I want to see with docstrings is "conforming-to", which specifies what
standard the procedure (or whatever) conforms to: ANSI, R5RS, SRFI, or
Guile original (what version).