[REBOL] Re: RFC: Examples in the auto-documentation
From: nitsch-lists:netcologne at: 24-Dec-2002 18:22
Ammon Johnson wrote:
>Hi,
>
> 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: ;-)
>
>my-func: func[
> "prints the value of a word"
> 'word [any-word!]
>][
> {my-word: "My word!"
> my-func my-word
> ;would return
> ;my-word is a word with a value of: "My word!"}
>
> print rejoin [word " is a word with a value of: " mold get word]
>]
>
>This is what you would currently 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)
>
>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?
>
to save space, we could have a #example in prebol, which appends its
argument to a text-file.
then help could search through the text-files. rebol can download the
documentation on demand.
like
#example{
my-word: "My word!"
my-func my-word
;would return
;my-word is a word with a value of: "My word!"
}
my-func: func[
"prints the value of a word"
'word [any-word!]
][
{my-word: "My word!"
my-func my-word
;would return
;my-word is a word with a value of: "My word!"}
print rejoin [word " is a word with a value of: " mold get word]
]
