[REBOL] RFC: Examples in the auto-documentation
From: ammon:addept:ws at: 24-Dec-2002 3:01
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?
Thanks!!
Ammon Johnson
CIO of Addept ---------- (www.addept.ws)
435.616.2322 ---------- (ammon AT addept.ws)
