Documenting generic types?

[lstephen]

Hi,

I've just started using jGrouseDoc and have looked around, but can not
find info on how to document generic types.

Say, for example, I have a custom Hash class. I would like to document
that a function takes a Hash with String keys, and objects of class
A.B as the values.

e.g., @param {Hash<String, A.B>} parameter

What would be the best way to do this?

Thanks,
Levi

[denis.r...@gmail.com]

Levi,

This functionality has not been implemented.

We had quite a lengthy discussion on this subject - see
http://code.google.com/p/jgrousedoc/issues/detail?id=29

Suggestions on the best way to do it?

Regards,
Denis

[lstephen]

>
> Suggestions on the best way to do it?

I think follwing the proposed syntax for the next javascript would be
a good idea (http://wiki.ecmascript.org/doku.php?
id=proposals:type_parameters). On quick reading that is the angle
brackets approach.

I think a simpler approach might be better and more flexible however.
Currently it is possible to specify as a type something like
'A.MyGenericClass[B.AnotherClass]' (angle brackets are currently
discarded I think) and it appears fine in the docs, except for linking
the types. Maybe it would be good to not parse the type, but instead
to link anything that can be linked to? (Of course, I say this without
even partially digging into whether this is possible ;) ).

The second approach would automatically allow specification of types
like: '[A.ClassOne, B.ClassTwo]' for tuple types, or something like
'{A.KeyClass, A.ValueClass}' to be used for Hash types. So, I guess
the on the pro side it allows great flexibility and allows the
documenter to decide on the best way to describe a type, but on the
con side, it means there is no standard way of documenting these
types.

Another unrelated question: Is there a 'best practice' for documenting
monkey patching functions? e.g., documenting something like
Array.extend({customMethod : function() {... }}) which adds a method
to the native Array class?

[denis.r...@gmail.com]

It is necessary to clarify which problem we are trying to solve:

- Specification of generic types
- Documenting of key/value types for hashes
- Documenting tuples

The problem of tuples is easily solved by declaring either an
interface/class/etc or by using the @... tag when describing return
type or parameter type.
The "general theory of universe" is harder to implement and not quite
sure if it is practical.

For hashes so far my personal favorite is ValueClass[KeyClass] with
square brackets. Note - it is assumed that constructions like
MyType[MyOtherType[BlahType]] being unreasonable exotics and won't be
supported :-)

How does that sound?

Regarding your last question - there are no best practices here, but
you can consider a number of options:
1. Simply declare /**@class Array*/ /** @function Array.myFunction
*/.
2. Put a number of functions into interface and then put something
like
/** @class Array
@implements MyInterface */
or you can use @extends tag

Would that work for you?

Regards
Denis

[Broofa]

On Feb 5, 3:57 am, denis.riabtc...@gmail.com wrote:
> For hashes so far my personal favorite is ValueClass[KeyClass] with
> square brackets. Note - it is assumed that constructions like
> MyType[MyOtherType[BlahType]] being unreasonable exotics and won't be
> supported :-)
>
> How does that sound?

We've been using the square bracket notation as well. While it's not
a rigorous solution to the generics problem, it works pretty well in
most cases.

> Regarding your last question - there are no best practices here, but
> you can consider a number of options:
> 1. Simply declare /**@class Array*/ /** @function Array.myFunction
> */.
> 2. Put a number of functions into interface and then put something
> like
> /** @class Array
> @implements MyInterface */
> or you can use @extends tag
>
> Would that work for you?

We just use approach #1. Works great.

[denis.r...@gmail.com]

Any other suggestions?
If the square bracket notation works fine, then I could add support to
parse it properly, thus providing linking to KeyClass (if applicable)

Regards,
Denis

[lstephen]

On Feb 5, 9:57 pm, denis.riabtc...@gmail.com wrote:
> It is necessary to clarify which problem we are trying to solve:
>
> - Specification of generic types
> - Documenting of key/value types for hashes
> - Documenting tuples
>
> The problem of tuples is easily solved by declaring either an
> interface/class/etc or by using the @... tag when describing return
> type or parameter type.
> The "general theory of universe" is harder to implement and not quite
> sure if it is practical.
>
> For hashes so far my personal favorite is ValueClass[KeyClass] with
> square brackets. Note - it is assumed that constructions like
> MyType[MyOtherType[BlahType]] being unreasonable exotics and won't be
> supported :-)
>
> How does that sound?

I think the syntax is not as important as the linking of types. So
square brackets would be fine.

It would be great to see the unreasonable exotics handled if possible
(consider a hash of a custom generic type).

>
> Regarding your last question - there are no best practices here, but
> you can consider a number of options:
> 1. Simply declare /**@class Array*/ /** @function Array.myFunction
> */.

Thanks, this works well. I did not think of using Array.myFunction
notation for defining functions. I had tried declaring the Array
class, but as I had it in multiple locations it didn't work so well.

Levi

[denis.r...@gmail.com]

OK, I will start thinking about the best way to do it. Maybe in a week
or two I would have something available. Cannot guarantee deep parsing
of complex types though. Will see how it goes.
Gosh, if someone would want to use a construct like
MySuperType[SuperHash[Key]][ComplexKey[SimpleKey]] then... well... I
would ask him if he works for a public company, so we could short
their stock :-) I still remember horrors of upgrading a C++
application using RougeWave libraries from VC6 to VC7 when MS changed
some #define statements in their libraries and the compiler was
spitting out a million of errors in template types with 5 levels of
nesting...

Regards,
Denis

[denis.r...@gmail.com]

Ha! I have added support for that syntax. It turned out to be
surprisingly simple :-)

Moreover, it supports even weird combinations like
/**
* @function {SomeType[String][SomeOtherType]} superFunction
* @param {SomeType[String]} param1
*/


Enjoy!

Regards,
Denis

[lstephen]

Thanks for that. I'll give it a go.