[REBOL] Re: RFC: Examples in the auto-documentation
From: gerardcote:sympatico:ca at: 24-Dec-2002 15:19
Hi Ammon,
> If you have used REBOL for very long you have probably discovered the power of
the HELP or ? function. I have noticed,
however, that it just barely falls short of a true HELP system. There are no examples
given. I would love it if there was a way to
make this happen. Maybe by having the first string in the function declaration block
be the example. For example: ;-)
[...]
> I propose that we get:
>
> >> ? my-func
> USAGE:
> MY-FUNC 'word
>
> DESCRIPTION:
> prints the value of a word
> MY-FUNC is a function value.
>
> ARGUMENTS:
> word -- (Type: any-word)
>
> EXAMPLE:
> my-word: "My word!"
> my-func my-word
> ;would return
> ;my-word is a word with a value of: "My word!
>
> By doing it this way it would enhance the system without breaking anything, or
causing any backwards compatibility issues.
Any thoughts or comments?
I also thought about this - and this would be a fine addition. However I think that this
would be to much overcharge for the Actual
Footprint of REBOL.
In fact I would prefer an external add-on Help system that could be called automatically
by the main REBOL engine if he is finding
such external reference in the user.r or pref.r.
This could so be added only by the ppl. that really need this kind of HELP without bothering
thos that don't need it and this could
be changed locally if anybody wants it to do so. to suit the language and personal additions
-
But then there should also be some way to submit any new additions to a central database
repositary that the RT or some delegate
could maintain for them under approval ...
For the data formats, I didn't think about them but you already got an overview for the
possible final results from the official
REBOL dictionary. However I don't really know how this can be handled internally by REBOL
and I leave this exercise to others.
Regards,
Gerard