simple module example generates a lint error

[jfirebaugh]

index.js:

'use strict';

/**
 * Square a number.
 * @param {number} x - base
 * @returns {number} x²
 */
module.exports.square = function (x) { return x * x; };

documentation --lint output:

    3:1  warning  @memberof reference to index not found

I tried using an explicit @module:

'use strict';

/**
 * @module test
 */

/**
 * Square a number.
 * @param {number} x - base
 * @returns {number} x²
 */
module.exports.square = function (x) { return x * x; };

documentation --lint output:

    3:1  warning  @memberof reference to test not found
    7:1  warning  @memberof reference to test not found

[jfirebaugh]

Proposed fix here is a two-parter:

1. When documentation infers module membership, but there is no explicit @module comment, it should synthesize one. For index.js or other package main files, it can pull the module name and other metadata from package.json. For non-index.js/main files, the synthesized @module should get the name from the file name.
2. Membership inference should skip @module comments.

[anandthakker]

👍

On Thu, Dec 10, 2015 at 2:07 PM John Firebaugh notifications@github.com
wrote:

Proposed fix here is a two-parter:

When documentation infers module membership, but there is no explicit
@module comment, it should synthesize one. For index.js or other
package main files, it can pull the module name and other metadata
from package.json. For non-index.js/main files, the synthesized @module
should get the name from the file name.
2.

Membership inference should skip @module comments.

—
Reply to this email directly or view it on GitHub
#295 (comment)
.

[akiellor]

@jfirebaugh in the 1. case, would you expect a '@moduleof' tag to be synthesized also. Example:

'use strict';

/**
 * Square a number.
 * @param {number} x - base
 * @returns {number} x²
 */
module.exports.square = function (x) { return x * x; };

is expanded to:

'use strict';

/**
 * @module test
 */

/**
 * Square a number.
 * @memberof test
 * @param {number} x - base
 * @returns {number} x²
 */
module.exports.square = function (x) { return x * x; };

[jfirebaugh]

would you expect a '@moduleof' tag to be synthesized also

Did you mean @memberof? Module membership inference is already implemented for assignments to module.exports properties.

[akiellor]

Yes sorry. I meant memberof.

I'm sorry these sound like silly questions, I'm using this change to get my head around the code base.

With the little prodding I've been doing, as you say the memberof inference is happening, but we want module inference (which should be similar to the module.exports case of membership inference).

My test:

//square.js

/** squares number
 * @param {number} n
 * @returns {number}
 */
module.exports.square = function(x) { return x * x }

$ bin/documentation.js build square.js

[
  {
    "description": "squares number",
    "tags": [
      {
        "title": "param",
        "description": null,
        "lineNumber": 1,
        "type": {
          "type": "NameExpression",
          "name": "number"
        },
        "name": "n"
      },
      {
        "title": "returns",
        "description": null,
        "lineNumber": 2,
        "type": {
          "type": "NameExpression",
          "name": "number"
        }
      }
    ],
    "loc": {
      "start": {
        "line": 1,
        "column": 0
      },
      "end": {
        "line": 4,
        "column": 3
      }
    },
    "context": {
      "loc": {
        "start": {
          "line": 5,
          "column": 0
        },
        "end": {
          "line": 5,
          "column": 52
        }
      },
      "file": "/Users/akiellor/src/documentation/square.js",
      "code": "/** squares number\n * @param {number} n\n * @returns {number}\n */\nmodule.exports.square = function(x) { return x * x }\n"
    },
    "params": [
      {
        "title": "param",
        "description": null,
        "lineNumber": 1,
        "type": {
          "type": "NameExpression",
          "name": "number"
        },
        "name": "n"
      },
      {
        "title": "param",
        "name": "x",
        "lineNumber": 5
      }
    ],
    "returns": [
      {
        "title": "returns",
        "description": null,
        "lineNumber": 2,
        "type": {
          "type": "NameExpression",
          "name": "number"
        }
      }
    ],
    "name": "square",
    "kind": "function",
    "memberof": "square", <<< The memberof inference
    "scope": "static",
    "members": {
      "instance": [],
      "static": []
    },
    "path": [
      "square"
    ]
  }
]

With all of that in mind, shouldn't this mean that the original lint error is impossible to encounter and thus should be deleted?

Should the desired output for this case include an additional comment for the module?

OR should it result in marking the existing comments as part of the module i.e. add it to the functions comment?