Allow constructors to specify value type

[puzrin]

https://github.com/nodeca/ndoc/issues/59#issuecomment-19039762

new Foobar(param) -> Type causes fatal error. I don't know, if such notation is useful, but it costs nothing to implement.

[deepsweet]

imo it should not throw an error at least because constructor may return more than just this by default.

i'll use this feature.

On Friday, June 14, 2013, Vitaly Puzrin wrote:

#59 https://github.com/nodeca/ndoc/issues/59#issuecomment-19039762

new Foobar(param) -> Type causes fatal error. I don't know, if such notation is useful, but it costs nothing to implement.

— Reply to this email directly or view it on GitHubhttps://github.com/nodeca/ndoc/issues/69 .

[puzrin]

ndoc throws error on syntax mismatch. I guess, original pdoc does not allow it too. But, as i said, i don't see principal problems in syntax extention.

/cc @ixti

[ixti]

Constructor can't return anything but this. When you use constructor as a function for a side effect., it's not making constructor return something else. In this case you should simply add two doc-blocks:

/**
 *  new Foobar()
 *
 *  Description of a constructor. In docs it will be explicitly
 *  named as constructor.
 **/

/**
 *  Foobar() -> String
 *
 *  Description of a constructor used as a function.
 **/

[deepsweet]

/**
 *  class Foobar
 *
 *  Class desc.
 **/

...

/**
 *  new Foobar()
 *
 *  Constructor desc.
 **/

/**
 *  Foobar() -> String
 *
 *  Constructor function desc.
 **/
var Foobar = function() {
    ...
    return 'abc';
}

throws name clash: Foobar error.

I'm a little confused :-/ without Foobar() -> String block everything is ok.

[ixti]

Ah, right! Indeed. Problem here is that in the way we build AST of doc nodes - we don't separate functions from classes, so for class Foobar AST node will have id Foobar, for it's constructor it will be Foobar.new, for function Foobar AST node id will be Foobar (same as in class) and this causes name conflict.

So either the example above will work either in case if you will avoid class Foobar docblock, or Foobar() -> String. In order to make this work we will need to rework AST building and I don't see obvious solutions here.

Idea of specifying constructor signature as new Foobar() -> String seems awkward to me. new Foobar will always return an object of Foobar prototype, so it looks really strange. Also in documentation it will be called constructor.

Can you please provide an example when constructor used as function for side effects (not just a shorthand syntax of new ProtoName)?

[puzrin]

Ndoc 3.0.1 allows to assign value for constructor. That's not documented feature, and it's not guaranteed to work in future. But i think, it will not be used widely. So, it will not be a problem to update docs when something changed.

Anyway, we can't spend time now for rewriting AST. If @deepsweet requirement is solved, i would close this ticket.