Lisp calls this sort of thing a "documentation string". One nice
thing about the Lisp syntax is that it works even if the Lisp doesn't
support docstrings!
We can also do this. Consider this (upcoming) Perl6 code:
sub foo {
"Snarf the frobnitzers if x > 0.1";
my $x = shift;
# ...
}
It is perfectly legal Perl5; there is a useless use of a value in void
context, but that's all.
Another alternative would be Javadoc / doxygen / ... style comments
(say #@ introduces a comment to be extracted).
Since the Perl interpreter doesn't need to know about documentation,
I'm for anything that doesn't require it to do anything.
Typing is also nice for this sort of thing; if we say
##@ Update DiLithium levels
sub foo(int $x) {
my DiLithium $ret;
# ... all returns are via $ret ...
$ret;
}
then Perldoc6 should be able to know that foo has type int ->
DiLithium.
--
Ariel Scolnicov |"GCAAGAATTGAACTGTAG" | [EMAIL PROTECTED]
Compugen Ltd. |Tel: +972-2-6795059 (Jerusalem) \ We recycle all our Hz
72 Pinhas Rosen St. |Tel: +972-3-7658514 (Main office)`---------------------
Tel-Aviv 69512, ISRAEL |Fax: +972-3-7658555 http://3w.compugen.co.il/~ariels
