Comments

eiriksm’s picture

StatusFileSize
new3.64 KB
eiriksm’s picture

Status: Active » Needs review
dawehner’s picture

+++ b/core/modules/views/js/base.js
@@ -41,9 +43,12 @@
    * @return {object}
+   *   An object containing the view path and the view arguments.

Do you mind describing that this object consists of 'view_args' and 'view_path'

eiriksm’s picture

StatusFileSize
new28.94 KB

Good point.

Just tried something, did not know it was allowed in jsDoc, but it is.:

* @return {object} returnObj
   *   An object containing the view path and the view arguments.
   * @return {string} returnObj.view_args
   *   The view arguments.
   * @return {string} returnObj.view_path
   *   The view path.

This produces the output attached. Which is very descriptive. Should we do something like this? Have not seen it done like this other places, and not in PHP docs either. So, a suggestion I guess.

dawehner’s picture

It is quite astonishing how much you can do with jsdoc.

eiriksm’s picture

So is that a "go" for this solution? :)

Maybe we should get some js/doc maintainers to look at it as well?

eiriksm’s picture

Talked to @nod_ in IRC, he also thought this @return stuff looked good. Submitted a question to the jsdoc team to be 100% sure this is supported (since this is not in the jsdoc doc).

eiriksm’s picture

Found this discussion on the jsdoc mailing list:

https://groups.google.com/forum/#!searchin/jsdoc-users/@return/jsdoc-users/TMvUedK9tC4/jQW3UBTaBR4J

This solution is in that answer called "faking it". Not sure if we should conclude with that that means it is supported :p

One thing we could do would be number 3 there. But it is a bit verbose though. Thoughts?

3. Define a Type

This solution assumes you want the benefits of separate docs but don't want to actually write a new class into your code. It's a bit halfway.

````
/**
@typedef generatedPoint
@type {Object}
@property {number} x The x coordinate.
@property {number} y The y coordinate.
*/

/**
* Generate a point.
*
* @returns {generatedPoint} The point generated by the factory.
*/

var pointFactory = function(x, y) {
return {
x: x,
y: y
}
}
````

nod_’s picture

Status: Needs review » Needs work

Let's not fake it. Just need the description to be explicit about what is in the object, we can discuss later about generalizing the use of custom types for this kind of things.

nod_’s picture

Status: Needs work » Reviewed & tested by the community
StatusFileSize
new441 bytes
new3.63 KB
webchick’s picture

Status: Reviewed & tested by the community » Fixed

Committed and pushed to 8.0.x. Thanks!

  • webchick committed 267a86a on 8.0.x
    Issue #2531694 by eiriksm, nod_, dawehner: JSDoc views module
    

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.