[REBOL] Re: documenting
From: al:bri:xtra at: 31-Aug-2002 9:08
jose wrote:
> Do you consider that your Values functions are in to the higher
documentation standard ? To me, that is the basic way to document proposed
by rebol and more than enough (in fact more than basic, because you include
Example in many headers and I recall RT has separate files with more info
like examples, etc..). I don't view that as a rewrite. What ideas you have
on this ?
Sorry, I misunderstood your post. I had believed that you needed to document
just one function, implying that the author of the function didn't
understand the function's purpose well enough to write a good description as
Rebol code. Sorry about that.
Most of my Values functions include the Example in the header, which is
useful when I forget how to use the function! (That's a sign to me that the
function probably isn't intuitive enough yet.) I also need to revisit those
few that aren't up to scratch and fix them up.
> Going back to your Values lib, I'm sure you have very useful functions but
without an automatic summary like the one I propose it's hard for others to
adopt (think of learning rebol core but not having a list of the functions,
..)
Yes, this automatic summary would be very good. A dictionary can be
generated by loading all the scripts in the Values/ directory (basically
running the %Values.r script from %User.r) and simply running the dictionary
script from Rebol.com. http://www.rebol.com/view/docs/make-ref.r Which
(after fixing a bug in my %Patches.r script), doesn't actually show my
Values/ functions? Hmmm...
I feel that the dictionary idea is best, once I find out how to get my
Values/ to be included.
Does anyone know how to do this? I'm almost sure it's probably a simple
modification of make-ref.r
Andrew Martin
ICQ: 26227169 http://valley.150m.com/
