Documentation not recognized after function statement

[GoogleCodeExporter]

This is an enhancement request (no template is available for that). Could
jsdoc be modified to recognize the following as valid documentation comment?

A.prototype.update = function(a) /** update this object */
 {
 }

Why? I use a code folding editor (jEdit) that hides indented lines so:

This takes 2 lines:
/** update this object */
A.prototype.update = function(a)

This is ugly:
/** update this object */ A.prototype.update = function(a)

This makes the comment initially invisible in the sourcecode until you
expand the function before:
    /** update this object */
A.prototype.update = function(a)

Original issue reported on code.google.com by katz...@gmail.com on 29 Dec 2008 at 9:05

[GoogleCodeExporter]

Additionally, using prototype.js I need to place the comment between the extend 
and
constructor statement, which is not ideal.

Object.extend(B.prototype,A.prototype);
/** @constructor @augments A  
    and a loooong description */
function B()
    { }

BTW: Thanks for jsdoc, its a very nice tool.

Original comment by katz...@gmail.com on 29 Dec 2008 at 9:14

[GoogleCodeExporter]

I see what you mean, but, knowing the internal changes required, I don't think 
that this sort of change would be 
possible. Well, okay, anything's possible, but it would require a major rewrite 
of jsdoc-
toolkit/app/lib/JSDOC/Walker.js

If you want to try it yourself and submit a patch there is a better chance of 
it being accepted.

Original comment by micmath on 29 Dec 2008 at 12:53

• Added labels: Type-Enhancement

[GoogleCodeExporter]

Ok, I will try. But need some help to locate where the comment is parsed ...
Your documentation hints that there should be already an inline parser for this
purpose installed:

http://code.google.com/p/jsdoc-toolkit/wiki/InlineDocs
Shows Example 2 like this:
function getPerson(/**String*/ name) /**Array*/ {
}

Could you tell me where Array is parsed? In Walker.js?

I tried it but Array seems not to appear in the output of a normal function. 

Using a parser generator like JavaCC (wikipedia:JavaCC) might have mede things 
easier
for you.

Original comment by katz...@gmail.com on 30 Dec 2008 at 10:34

[GoogleCodeExporter]

After looking at it, the answer appeared to be: Array is parsed nowhere! 
Apparently the documentation was 
not correct and the inline comments for return types was never implemented!

Anyway, based on your question, I did implement support for inline comments for 
return types, committed in revision 753.

Unfortunately this fix makes your work impossible because you can no longer 
tell the difference between 
this...

    function getPerson() /**Person*/ {

and this...

    function getPerson() /**Get the Person*/ {

Also I'm not sure how JavaCC would make things easier, but feel free to 
explain. One of my personal goals for 
this project was to implement it completely in JavaScript. In fact all of the 
early releases actually ran in any 
web browser, but I later settled on Rhino as a good host environment. The 
tokenizer though _is_ pure JS, and 
works well; certainly the tokenizer isn't what would prevent you from 
implementing your requested feature.

I am eagerly waiting for Rhino 1.7R2 to become final, as it will support user 
generated parse trees, and so will 
make the job of supporting new language features simple, but it still wouldn't 
make this request easier to 
implement, so not sure what you mean.

Original comment by micmath on 31 Dec 2008 at 12:24

[GoogleCodeExporter]

Ok, I implemented it. See the attached patch or use the whole file Walker.js

    function getPerson() /**Person*/ {
    function getPerson() /*** This is a doc comment for the whole function. */ {

function getPerson()
   /*** This is a doc comment for the whole function. 
        @type Person
      */ 
{

If you ever think of starting a new parser project consider JavaCC. It uses 
Backus
Naur Form to specify the parser. Writing a parser from scratch is quite more
difficult and often error prone. Though such a project requires Java. For this
project the discussion is too late. Your parser requres doc @-tokens at separate
lines. A parser generator makes no such assumptions.

Original comment by katz...@gmail.com on 31 Dec 2008 at 11:34

Attachments:

• Walker.js
• jsdoc-toolkit.diff

[GoogleCodeExporter]

I don't see how

function getPerson()
   /*** This is a doc comment for the whole function. 
        @type Person
      */ 
{

is better than

/**
    This is a doc comment for the whole function. 
     @type Person
 */ 
function getPerson() {

And yet it is different than any other implementation of JsDoc or JavaDoc I've 
ever seen. Also if the doc 
comment is particularly long (I've seen some that take up most of a screen) 
you've visually orphaned the 
function name & params from its body. Your patch would really only be useful 
for one-liners, which is, in my 
experience, pretty rare in the wild.

After considering it I'd say: you're welcome, of course, to use and distribute 
this patch (I wrote JsDoc Toolkit in 
JavaScript precisely to make it easy for users to customize) but I'm not keen 
to include it in my repository 
because I think it would be confusing to have yet another kind of doc 
comment--a "three star" one--when 
the need for it is so limited.

Original comment by micmath on 31 Dec 2008 at 3:10

• Changed state: WontFix

[GoogleCodeExporter]

Of course there are other alternatives than the three star version.
Doxygen uses /**<, //!<, /*!< (Qt-style) and ///< as identifier for putting
documentation after members (and doxygen is standard). 

Maybe /**< would be the right choice?

As I said before, it is a primary choice for short comments. Long comments still
would go before the function name, though this is up to the programmer. In 
Python for
example all doc comments are positioned after the function declaration (even if 
pages
long). 

Take a look at this:
http://www.stack.nl/~dimitri/doxygen/docblocks.html

Original comment by katz...@gmail.com on 31 Dec 2008 at 3:31

[GoogleCodeExporter]

JsDoc is not defined in any "standard" but there is JSDoc.pl, ScriptDoc, 
YuiDoc, and JsDoc Toolkit varients in 
current use, so there are some de facto standards. All of these are inspired by 
JavaDoc. In all cases the 
comment goes before the thing being documented. In my opinion you would have to 
make an extraordinarily 
strong case for changing that, and I haven't yet heard such.

Presumably you can already use Doxygen to document your code, so why should I 
try to make JsDoc Toolkit 
more like Doxygen? Or you could customize JsDoc Toolkit to do something 
different, which you have. But I'm 
still not convinced this should be in the repository. If you still want to make 
your case you should post your 
idea to the user group, and I'll consider whatever the reaction/interest there 
is.

If you feel very, very strongly you could always fork the project or start your 
own (it's already happened 
before) and, as long as you adhere to the license of any code derived from my 
work, you will have my best 
wishes and support.

Original comment by micmath on 31 Dec 2008 at 10:58

[GoogleCodeExporter]

Well, I will do my best to convince you that 'post member comments' are not a 
bad
thing (no bad feelings) :-). Whether they are a good thing you must let the
individual user decide. I personally would see a use for /**<, /// and ///< 
comments.
Why javadoc does not provide them - I do not know.

I think that every programmer develops his/her own style and uses other tools 
like
folding editors. A commenting tool needs to work together with other tools in 
use. It
should not prescribe where one puts comments or how one uses the tool. 
Otherwise it
is less useful or inconvenient to use. If you do not use a folding editor post 
member
comments are useless, because you have to look at all code anyway. See screen 
shot
for a folding example. 

In my opinion it is useful to look at what other tools do, but not blindly do 
the
same, because that would allow no progress. One has to look at how to improve a 
thing
beyond what is standard today and think out of the box. So whatever we call 
standard
is per definition old and not cutting-edge.

No, doxygen is not javascript ready. No, I will not fork your project (I would 
rather
start from scratch based on JavaCC). I have already one and a half projects on
sourceforge and it would be a waste of resources. In my opinion OpenSource 
authors
should work together instead of creating too many forks.

I think this discussion should be continued outside of the issue tracker in 
future. I
am sad that you do not share my opinion that post-member comments are useful. 
Anyway,
thanks for your tool.

Original comment by katz...@gmail.com on 2 Jan 2009 at 11:53

Attachments:

• screenshot.tiff