Add Interface support (@interface and @implements)

[GoogleCodeExporter]

Yes, Interface. Although JavaScript doesn't support Interfaces "naturally",
some libs mime this behaviour.

Libs like the $class by useless pickless do:
http://www.uselesspickles.com/blog/the-class-library/

So I wish @interface and @implements as tags. As for now this is the k.o.
criteria not using jsdoc :(

Original issue reported on code.google.com by unigossi on 5 Aug 2009 at 8:32

[GoogleCodeExporter]

Additionally, where interfaces are declared, they may be declared using in 
static
object style:

@interface 
var Drawable = {
   drawMe: function() {}
}

In this case (the object is an interface) the method should not be reported as
'static' as it is at the moment.

Original comment by lindsay....@gmail.com on 13 Aug 2009 at 1:48

[GoogleCodeExporter]

Original comment by micmath on 21 Aug 2009 at 2:08

• Added labels: Type-Enhancement

[GoogleCodeExporter]

The part about declaring interfaces statically can be currenctly implemented
something like this:

/**
 * @class
 */
var Drawable = 
/**  @lends Drawable.prototype */
{
   drawMe: function() {}
}

Original comment by lindsay....@gmail.com on 25 Aug 2009 at 12:47

[GoogleCodeExporter]

I also hope there can be explicit tags for interfaces, since the interface 
might not
be static (I use an Interface class to create interface objects), and even if 
it is
static, it should, I feel, be immediately clear what its purpose is

Original comment by bret...@gmail.com on 25 Aug 2009 at 9:57

[GoogleCodeExporter]

Just a few further thoughts...

Given JavaScript's ability to easily use duck typing, without needing to 
declare a
formal interface (indeed, it seems having such comments could sometimes be used 
to do
the interface checking), I would also think it helpful to have a means of 
defining an
interface within the comments (not only being able to reference an existing 
interface).

I'm not clear on whether the "Parameters with Properties" feature described at
http://code.google.com/p/jsdoc-toolkit/wiki/TagParam can be used with instance
methods, e.g.,:

@param obj#reqdMethod1
@param obj#reqdMethod2

...but this could be one useful though not succinct way to indicate the specific
methods required of an interface (which may be useful if one later decides to 
break
up an interface).

However, I think it may be nice to have a more compact syntax, e.g.,

@implements someIntf reqdMethod1, reqdMethod2 [2], reqdMethod3 [3,]
reqdMethod4 [arg1, arg2], 

...where either no arguments were required, a required argument count, a minimum
argument count, or argument names could be used (the argument checking is less
critical, however).

It would be great if such interfaces could be auto-documented separately if 
they are
not already defined as objects.

Maybe distinctions could be made by those checked at run-time, those that can be
checked before run-time, and those which can only be checked at run-time but for
which no mechanism has yet been added.

Original comment by bret...@gmail.com on 29 Aug 2009 at 2:19

[GoogleCodeExporter]

My company have a very large Javascript API that makes copious use of 
interfaces. We are stuck using jsdoc.pl (hacked to add @interface and 
@implements) so the jsdoc we ship clearly distinguishes these important 
differences. For us, @interface is essentially a synonym for @class, and 
@implements is essentially a synonym for @extends. The only difference is that 
in our jsdoc output we show a blue I icon and italic text to distinguish 
interfaces, and we show the the list of classes we extend versus the list of 
interfaces we implement separately, like JavaDoc does.

Having this feature will probably allow us to migrate to jsdoc toolkit. Thanks, 
Dominic.

Original comment by dominic....@gmail.com on 24 Jun 2010 at 5:08

[GoogleCodeExporter]

JSDoc 3 will support the @interface and @implements tags natively, but you can 
already use them in JsDoc Toolkit 2 if you treat them as "custom tags". In fact 
any tag you can imagine can be used this way, you just need to modify the 
template (something that is designed to be modified, so is not a hack).

see http://code.google.com/p/jsdoc-toolkit/wiki/FAQ#Using_custom_tags

Original comment by micmath on 24 Jun 2010 at 11:46

[GoogleCodeExporter]

Excellent, thanks for clearing this up.

Original comment by dominic....@gmail.com on 25 Jun 2010 at 9:00

[GoogleCodeExporter]

Original comment by micmath on 27 Jun 2010 at 8:56

• Added labels: Milestone-Release3.0