I remember WSDOC from APL. Using a few formatting rules in making comments
WSDOC could construct documentation for a workspace. Note could provide a
similar tool. The left argument could name the definition to which it
applies and possibly additional internal information. If a script contains
one or more Note verbs they execute immediately as all its arguments are
satisfied. Note can extract and save things from its arguments.
One possibility is the y argument could be saved and popped up if one
hovers the mouse over the name.
'mean' Note 'Calculate the mean ignoring an optional left argument'
Example:
'see?' mean 2 3 5 7
4.25
Description:
Hey guys. It's a hook. Really sneaky!
)
mean=:] +/ % #
Yes, I know that right now Note is monadic only.
I'm not saying that this is what should be done. But Note provides a way to
use documentation for a definition for helping users understand what it is
for and how to use it without having to study the definition itself.
As to reading definitions. It helps a lot if one is told what a definition
is intended to do and what it expects for arguments. The names assigned to
a definition many times describes what it is for and makes obvious what its
arguments should be. But for many the name is not enough. Take, for
example, "splitnostring". It's not clear what it does or how to use it. It
might be the very thing I need, but I have no practical way of knowing. And
I doubt I would take the time to analyze it just to see what it does. (OK,
so the "no" in it means number. But it could also mean no string at all. A
little confusing. Maybe "splitnumstring" would be a clearer name.)
And writing documentation, particularly good documentation, is not easy.
Not much fun either. But describing what something is supposed to do, how
to use it and possibly generally how it goes about doing it can make it so
much easier to understand and use something. I don't mean repeating in
English step by step what each line does. That's where reading and
understanding the J statements come in.
It's too easy to write J and also many other languages. We can solve
problems without fully understanding the problem. Look at all the apps
appearing in Android. Many are really bad. I find that forcing myself to
document something helps me more fully understand the problem, possibly
finding errors I have missed before. And if I come back to it in a year or
so, it takes a lot less time to figure out what I did.
I have a feeling that you all already know all this. But I just had to say
it.
>
>
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
