#101 Computed doc-comments
At
http://www.eros-os.org/pipermail/e-lang/2004-April/009819.html
Kevin Reid writes:
On Apr 29, 2004, at 22:06, Mark S. Miller wrote:
> At 06:06 PM 4/29/2004 Thursday, Kevin Reid wrote:
>
>> Why not allow doc-comments to be parameterized, so
that interactive
>> help for an object does not need circumlocutions
describing its most
>> general behavior?
>>
>> def makeAdder(k) :any {
>> /** Adds $k to the given number. */
...
> That's very clever. Nothing like it had ever occurred
to me. But what
> you
> put on statically generated (javadoc-like)
documentation pages? I'd
> like to
> use doc-comments to support both online and offline
documentation
1. Ignore the problem. Assume that the expressions will
be reasonably
readable in context when reading the source, and that
documentation
tools will be able to extract sufficient information to
provide useful
documentation. (For example, my original example would
be fine,
provided that the documentation tool includes parameter
names and
preserves lexical scoping.)
2. Static-mode alternatives, readable by documentation
tools.
/** Adds $?{k}{"some constant"} to the given number. */
where the
second brace-enclosed expression must contain no free
variables.
3. Leave it up to the programmer to implement
__getAllegedType to
substitute the dynamic information into the existing
doc-comment, and
provide a suitable call-the-miranda-method primitive.
Functions could
be provided to help with this process.
def makeAdder(k) :any {
/** Adds some constant to the given number. */
def adder {
to __getAllegedType() :any {
substituteDocComments(
meta.callMiranda(adder, "__getAllegedType", []),
["some constant" => k]
)
}
to run(n) :any {
return k + n
}
}
return adder
}