[gambit-list] Documentation

Jason Felice jason.m.felice at gmail.com
Fri Jun 21 12:31:19 EDT 2013


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 at 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 at iro.umontreal.ca>
>
>>
>> On Jun 20, 2013, at 10:09 AM, Guillaume Cartier <gcartier at 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 at iro.umontreal.ca
>> https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list
>>
>
>
> _______________________________________________
> Gambit-list mailing list
> Gambit-list at iro.umontreal.ca
> https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.iro.umontreal.ca/pipermail/gambit-list/attachments/20130621/f6873bca/attachment.htm>


More information about the Gambit-list mailing list