I've been thinking about inline documentation and documentation-in-REPL, and I came up with the following ideas:

1. If there's some kind of unique per-compiled-function identifier that is consistent across runs, this can be used to look up documentation in an external file.  If a tool is made to scrape doc comments and produce this database, then there will be no runtime bloat if the documentation is never accessed.
2. It doesn't seem to be a big deal to bloat interpreted functions, though making interpreted functions keep their documentation comments would require a kind of weird and non-trivial extension to the reader.  BUT, it would still be really cool.
3. Python-style doc strings, _if_ the compiler knows to optimize them out, would be a simple solution and wouldn't require a strange reader.  e.g.

(define (map proc l)
#<<END_OF_DOC
(map proc l)

   Does such and such...
END_OF_DOC
  ...)

Thoughts?


On Thu, Jun 20, 2013 at 2:41 PM, Mikael <mikael.rcv@gmail.com> wrote:
Just provide a very very clear format and structure for how this documentation should be committed into and represented in the repo, and I'm sure there's people who are happy to contribute.

What in the documentation can be cleaned up?

2013/6/20 Marc Feeley <feeley@iro.umontreal.ca>

On Jun 20, 2013, at 10:09 AM, Guillaume Cartier <gcartier@jazzscheme.org> wrote:

> There is also the 6.4 Undocumented extensions section in the Gambit manual that is there for this purpose, correct me if I'm wrong Marc.

In principle that section if for documenting the existence of procedures that don't have documentation.  I see that the first few are documented and should be moved elsewhere!  The documentation should be cleaned up.  Are there people out there with some free time and a generous nature?

Marc

_______________________________________________
Gambit-list mailing list
Gambit-list@iro.umontreal.ca
https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list


_______________________________________________
Gambit-list mailing list
Gambit-list@iro.umontreal.ca
https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list