Nested name value support for @prop and @property about doctrine

[nzakas]

I'm still seeing problems with 0.4.0, do I have to do something to turn this functionality on?

/**
* Description
* @param {Object} p bar
* @param {string} p.foo A bar property.
* @returns {string} desc */
Foo.bar = function(p){};

This is what gets created:

  { title: 'param',
  description: 'bar',
  type: { type: 'NameExpression', name: 'Object' },
  name: 'p' }
{ title: 'param',
  description: '.foo A bar property.',
  type: { type: 'NameExpression', name: 'string' },
  name: 'p' }

[jonathanKingston]

@nzakas It only operates currently on @prop or @Property the docs didn't seem to operate on others.

[nzakas]

It works for @param as well, it's just not documented in the JSDoc 3 site, but it is on the JSDoc Toolkit site: https://code.google.com/p/jsdoc-toolkit/wiki/TagParam

[jonathanKingston]

@nzakas damn, it does however seem slightly better practice to reference objects outside with typedef: http://usejsdoc.org/tags-typedef.html

I suspect this is the better way of defining for JSDoc3.

However I can add this in so at least it can be parsed, we can decide later if the usage should be a warning for JSDoc3 mode perhaps - the article appears to be fairly oldish.

[nzakas]

Maybe @hegemonic can shed some light on this? We use nested properties like this at work all the time.

[hegemonic]

@nzakas is correct--JSDoc 3 fully supports the "nested property" syntax for @param tags. I'll file a ticket to clarify that point in the @param tag docs.

[jonathanKingston]

@hegemonic thanks for clarifying, I might have to submit some further clarifications to you at some point. Like the inconsistent casings of type's particularly annoy me.

Does using @typedef for @param have the same / similar meaning in terms of the generated output?

[hegemonic]

@jonathanKingston, sure, feel free to ask questions anytime!

By "inconsistent casings of types," do you mean string versus String? JSDoc doesn't care how you capitalize JavaScript's built-in types. Personally, I prefer lowercase for types that are passed by value (string, number, boolean) and title case for types that are passed by reference (Object, Array.<string>). That's my own preference, though, not a JSDoc requirement.

In JSDoc 3, the semantics behind @typedef and nested-property @param are a little different:

• @typedef is meant for complex types (other than classes) that your code uses repeatedly. You document them once, then reuse them in type expressions.

  In JSDoc's default template, the docs for type definitions are not shown in-line with the list of method parameters. You have to click a link, which takes you to the type definition's docs.

• @param with nested properties is useful for one-off objects that are only passed to a single method. For example, you might use this for an options object.

Google Closure Compiler introduces another wrinkle. My understanding is that Closure Compiler encourages liberal use of @typedef but does not support the nested-property @param syntax (or, at any rate, does not encourage it).

[nzakas]

At work this is exactly how we use it. Typed efts for reusable things, nested properties for function-specific. Also, we enforce lowercase for primitive types and uppercase for reference types.

[jonathanKingston]

@hegemonic thanks for the clarification.

Yeah I meant just that, most developers seem to use casing to indicate something different.

I know it seems boring but what about each type parameter links to a page about validation? For example all @prop and @param linking to a name article about what is supported and how to validate.

For example its not clear if @namespace or @this or @member support this nested param nature.

Shall I file a ticket on JSDoc to clear this up?

[hegemonic]

@jonathanKingston: Off the top of my head, I can't think of any other JSDoc tags that use the nested-property syntax in the way we're discussing it here. It's only relevant for tags that can appear more than once in the same comment block.

Please feel free to file a ticket in jsdoc3/jsdoc3.github.com anytime you'd like something to be clarified in the docs. I'm painfully aware that they have a lot of room for improvement!