jsdoc - pod in JavaScript
jjore
and thought it would be of interest to this crowd.
I've been writing JavaScript libraries recently and wanted some nice
inline place to put documentation but also wanted a way to extract it.
This just feeds all the comments in your code to perldoc. Here's a
small example:
function mapcar (func, col) {
/*
=item ARRAY = mapcar( func, col )
Apply FUNC to each element of COL, and make an array of the
results. The result is an array just as long as COL. COL may be
anything that has a length attribute and can be indexed into
like an
array.
*/
var out = new Array();
for ( var i = 0; i < col.length; ++i ) {
var elt = col[i];
var val = func( elt );
out.push( val );
}
return out;
}
becomes...
=item ARRAY = mapcar( func, col )
Apply FUNC to each element of COL, and make an array of the results.
The result is an array just as long as COL. COL may be anything that
has a length attribute and can be indexed into like an array.
=cut
Burak Gürsoy
spec by putting ws in front of Pod directives. I don't think that JSAN
encourages such actions, since there is a Pod extractor/converter if
you pack your modules with Module::Build::JSAN :) This also seems to
waste cpu time by just fixing that paddings you've made :p
On 28 Şubat, 06:03, "jjore" <twi...@gmail.com> wrote:
> I recently posted "jsdoc - pod for JavaScript" athttp://perlmonks.org/?node_id=601829
jjore
> hmmm... seems nice, but this is not Pod since you are breaking the Pod
> spec by putting ws in front of Pod directives. I don't think that JSAN
> encourages such actions, since there is a Pod extractor/converter if
> you pack your modules with Module::Build::JSAN :) This also seems to
> waste cpu time by just fixing that paddings you've made :p
Surely you are joking about the CPU cost of removing indentation
outweighing the usefulness of the feature. Comments that are indented
to the same level of the code they are describing is a best practice,
it looks nice and that's what my editor does by default. When I first
read the recommendation in the example pod on openjsan, I thought it
was obvious that it was done that way purely because of the
limitations of pod.
Josh
Burak Gürsoy
Yes, I am :)
> Comments that are indented to the same level of the code they are describing is a best practice,
But, Pod != Comment. And I still think that this is not Pod. Btw, I
always put the Pod after __END__ in my perl codes and I think that
this is the *best practice* according to The Damian :) And since Pod
is a Perl thing, this still applies to JSAN I think. Put your
documentation at the end and, if you really need to explain the api
somehow (i.e. it's usage is impossible to understand without a clue),
use normal comments instead. Like:
// call it like: foo({ blah: 1, bar: some_object })
function foo(znjdnf) { fgfhj4.uhjtyre( znjdnf.bar ) }
// ... some 200 line of JS
/*
=head1 NAME
...
=cut
*/