[IPython-dev] JavaScript docs...

[Matthias BUSSONNIER]

Le 7 juil. 2013 à 08:38, Fernando Perez a écrit :

> Just a couple of quick questions:
> 
> - is it possible to avoid all the * in the comments for the doc
> generation machinery? Technically JS only needs the matching /* */
> pair, so unless the doc tools need all the extra * on every line,
> those could be skipped.

Apparently Yes it can be skipped but it still need the double asterisk on the first line
and only spaces on subsequent line would be accepted, not stuff like

/**
//
//
//
//*/

> 
> - it it OK to put the 'docstring' after the function declarations,
> like in python?

It works, but the doc will link the declaration of the function on the line following the docstring.

> That seems quite a bit more python-like and readable to me...

If you decide to go this way, so be it, but JS is not Python, and I don't think
we should try to match Python on this one.

It will still be frustrating as our editors will still try to fill the comment with leading * when writing. 
we will not get use to docs of other js project, and we will drive js-contributor crazy in not following 
language convention.

-- 
Matthias