[REBOL] Re: RFC: Examples in the auto-documentation
From: micael:gullmes:telenor:se at: 24-Dec-2002 12:48
Hi Ammon,
Example's in the helptext is a good idea.
I believe that using an optional {} to get everyone to add example's in their func's
will not make everyone do so.
You can get the same result using the current syntax, see the modified example below.
I have also added a modified func version which gives this capability more 'nativley'.
Brgds /Micael
;----simple change to my-func which gives an example text-------------------
my-func: func[
{prints the value of a word
EXAMPLE:
my-word: "My word!"
my-func my-word
;would return
;my-word is a word with a value of: "My 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]
]
;----------------------------------------------------------------------------
If you really want to change the behavior of func to handle an example refinement:
Something like this (it needs prettier print method though)
;----changes to Rebol's "func" which gives an example text-------------------
func: func [
"Defines a user function with given spec and body."
[catch]
spec [block!] {Help string (opt) followed by arg words (and opt type and string)}
body [block!] "The body block of the function"
/example example_text [string!] "Example string (opt)"
][
if example [
if not string? first spec [
insert spec ""
]
append first spec rejoin [newline "EXAMPLE:" newline example_text]
]
probe spec
throw-on-error [make function! spec body]
]
;----example how to use changes to Rebol's "func" which gives an example text-------------------
my-func: func/example [
"prints the value of a word"
'word [any-word!]
][
print rejoin [word " is a word with a value of: " mold get word]
] { my-word: "My word!"
my-func my-word
;would return
;my-word is a word with a value of: "My word!
}
;----------------------------------------------------------------------------------------------
Brgds /Micael
-----Ursprungligt meddelande-----
Fr=E5n: Ammon Johnson [mailto:[ammon--addept--ws]]
Skickat: den 24 december 2002 11:02
Till: [rebol-list--rebol--com]
=C4mne: [REBOL] RFC: Examples in the auto-documentation
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)
