Support documentation of items within collections

[KylePDavis]

I'm looking for a way to document the types within an Array (or any other collection types, for that matter).

Possible implementations could be:

• {Array{type}} - nesting with curly braces -- seems the most consistent but that's my 2c
• {Array<type>} - nesting with angle brackets -- not bad, expected by C++ folks
• {type[]} - special handling to denote a collection -- okay, but loose the ability to say what kind of collection

Thoughts?

[dnutels]

And the output would be something like:

...
parameter Array of String 
...

?

I am just using {Array of String} as is with

...
parameter Array of String
...

being an output. A bit more PITA, but works.

[KylePDavis]

I have tried simply using a fake type as you suggested (like Array of String) but that breaks the type links in the docs so it's harder to follow. It can handle Array and String but when you give it Array of String it just sees that as a single type.

I would prefer something like Array<String> with Array and String being links to appropriate page in the generated documentation. That kind of format would probably be more obvious to more people and also more flexible when it comes to handling deeply nested types. I'm sure the person making the template could make it display however they wanted, though.

[davglass]

I'm not sure I like that. The type is an Array, the description can
take care of the contents of that array.

[KylePDavis]

You can mention the sub-type in the description but you can't easily describe it in a way that your readers can track down the type.

[asutherland]

For comparison purposes:

• jsdoc-toolkit supported the {ExampleType[]} variant: http://code.google.com/p/jsdoc-toolkit/wiki/TagParam
• jsdoc3 supports ExampleType[] and Array.<ExampleType> http://usejsdoc.org/tags-type.html . The latter stems from their support of the Google Closure Compiler type expressions: https://developers.google.com/closure/compiler/docs/js-for-compiler#types

[qraynaud]

I also believe it would be great if this could be supported somehow.

[antoinerousseau]

+1

[lexander]

@KylePDavis you can include explicit cross references as described in http://yui.github.io/yuidoc/syntax/index.html#cross-referencing-modules-and-classes

E.g.

/**
 * My example method
 * @method doThing
 * @param arg {Array} a collection with entries of type {{#crossLink "TestClass"}}{{/crossLink}}.
 * @return {Boolean} true if success if achieved
 */

produces output like:

<div id="method_doThing" class="method item">
    <h3 class="name"><code>doThing</code></h3>
        <div class="args">
            <span class="paren">(</span><ul class="args-list inline commas">
                <li class="arg">
                        <code>arg</code>
                </li>
            </ul><span class="paren">)</span>
        </div>
        <span class="returns-inline">
            <span class="type">Boolean</span>
        </span>
    <div class="meta">
                <p>
                Defined in
        <a href="../files/src_class.js.html#l38"><code>src/class.js:38</code></a>
        </p>
    </div>
    <div class="description">
        <p>My example method</p>
    </div>
        <div class="params">
            <h4>Parameters:</h4>
            <ul class="params-list">
                <li class="param">
                        <code class="param-name">arg</code>
                        <span class="type">Array</span>
                    <div class="param-description">
                        <p>a collection with entries of type <a href="../classes/TestClass.html" class="crosslink">TestClass</a>.</p>
                    </div>
                </li>
            </ul>
        </div>
        <div class="returns">
            <h4>Returns:</h4>
            <div class="returns-description">
                        <span class="type">Boolean</span>:
                    <p>true if success is achieved</p>
            </div>
        </div>
</div>

[KylePDavis]

Thanks @lexander for the work around.
I'd still like for us to come to a clean solution, though.
Using cross references for this seems unnecessarily cumbersome.

[esamattis]

I would also like to see this. I often have methods returning a Promise and it would be really nice if it could documented for example with the angle bracket syntax @return Promise<String>.

The cross link feature is a reasonable alternative but I feel it has a way too verbose syntax. Why not just render strings like {MyClass} or {MyClass#myMethod} to cross links from the description body?

[pnstickne]

Should talk to a VB guy .. while the following won't "link" the nested types, it will actually be processed, score +1 point.

Array(MyClass)

But really, I feel 😧 for YUIDoc and that it is stuck back in the Java 1.4 era which was over a decade ago. I must say I'm glad I'm only "passing through" YUIDoc and the above solution at least gives a little sense of consistency for tool processing ..

[shinout]

Only if they convert < to &lt;.
<Object> breaks layout...

[okuryu]

@shinout Is there a reproducible example?

[shinout]

@okuryu
Thanks for quick reply.
Here is an example.

###*
@class FooBar
###

###*
@method doSomething
@return {Promise<Object>}
###

the "return" part is converted to

<span class="type">Promise<Object></span>

the version of yuidocjs is v0.5.0, via grunt-contrib-yuidoc v0.7.0

Is the version old? Latest grunt-contrib-yuidoc still uses v0.5.0.

[okuryu]

Sorry for delay. It occurs in all YUIDoc versions, it seems not to be a regression. However, I'd like to work on this in the future.