Property/method distinction and @type support.

[donmccurdy]

If you're reporting a bug, please include input code, output documentation,
a description of what you expected to happen, and what happened instead.

Input

documentation build foo.js --format md --sort-order alpha

/**
 * Represents a foo, provides access to the bar and the zab.
 */
function Foo () {
  /**
   * It is the foo.
   * @type {number}
   */
  this.foo = 1;

  Object.defineProperties(this, /** @lends Foo */ {

    /** @type {number} It is the bar. */
    bar: {
      get: function() {
        return 2;
      }
    },

    /** @type {number} It is the zab. */
    zab: {
      get: function() {
        return 3;
      }
    }

  });
}


Object.assign(Foo.prototype, /** @lends Foo */ {

  /**
   * Gets the foo.
   * @return {number}
   */
  getFoo: function () {
    return this.foo;
  },

  /**
   * Gets the bar.
   * @return {number}
   */
  getBar: function () {
    return this.bar;
  }

});

Output

### Table of Contents

-   [Foo](#foo)
    -   [foo](#foo-1)
    -   [bar](#bar)
    -   [getBar](#getbar)
    -   [getFoo](#getfoo)
    -   [zab](#zab)

## Foo

Represents a foo, provides access to the bar and the zab.

### foo

It is the foo.

### bar

### getBar

Gets the bar.

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**

### getFoo

Gets the foo.

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**

### zab

---

Current/desired output

Setting aside the readability of this code (it's a reduced example based on https://github.com/dataarts/dat.gui), a few things are not being documented as I had hoped:

1. Methods and properties could be distinguished somehow. Even sorting alphabetically, I think I'd want properties first and then methods, perhaps with subheaders.
2. The @type tag isn't reflected for any of the properties; no type information shows up.
3. I often see @type used in oneliners as /** @type {number} Quantity of foo. */. I'm not sure if that's actually valid JSDoc, but curious for your thoughts. Here, the description is ignored when written this way.

Related to #906 and #246.

Thanks for writing this tool! Let me know if changes for any of this would be reasonable or wanted.

Other

• What version of documentation.js are you using?: 5.3.3
• How are you running documentation.js (on the CLI, Node.js API, Grunt, other?): CLI

[tmcw]

Sure, yeah - the Markdown documentation mode doesn't have a lot of the structure of the HTML output. The shape of the markdown documentation is decided by markdown_ast

Whether one-liners are valid JSDoc - that's one of the quibbles with JSDoc that I'm trying to avoid for the long term by quietly forming dx-spec, a stricter and more modern specification.

In the case of

/** @type {number} Quantity of foo. */

In particular, it sounds like documentation.js is doing what the spec suggests is the correct behavior: the type tag does not have a description attached to its {type} parameter, and tags are defined as always extending to the end of their line, so Quantity of foo is correctly ignored.

/** Quantity of foo.
   * @type {number} */

This would be parsed correctly and would be valid.

[donmccurdy]

Makes sense, thanks. I can do without the @type one-liners easily enough.

About (1) and (2), for the example above, what do you think of this as proposed output?

### Table of Contents

-   [Foo](#foo)
    -   Properties
        -   [foo](#foo-1)
        -   [bar](#bar)
        -   [zab](#zab)
    -   Methods
        -   [getFoo](#getfoo)
        -   [getBar](#getbar)

## Foo

Represents a foo, provides access to the bar and the zab.

### Properties

#### foo

It is the foo.

Type: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)

#### bar

It is the bar.

Type: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)

#### zab

It is the zab.

Type: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)

### Methods

#### getFoo

Gets the foo.

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**

#### getBar

Gets the bar.

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**

Loosely based on three.js docs, and would probably need to handle static properties/methods similarly. Here's how that might work in markdown_ast.js.