Dot Notation in @augments

[Dan Rzeppa]

Does JSDoc support using "dot notation" in @augments? I can't seem to get it to work.

I have two files. File1 looks like:

/**

* @constructor

*/

someObject = function() {}

File2 looks like: 

/**

* @constructor

* @augments file1.someObject

*/

otherObject = function() {}

I get a "Missing dependency: file1.someObject" exception when running these files through JSDoc.

It would be nice to qualify which object is being augmented, since multiple files may use the same object name. 

[Michael Mathews]

I'm assuming you are using JSDoc 3, but this would apply to any version of JSDoc. You can use dot notation, but filenames are not valid parts of a name. JSDoc expects a "namepath" to appear in the @qugments tag, which would be similar to the full name you would give to refer to that thing from the global scope. In your example the namepath to someObject would simply be "someObject", not "file1.someObject". As an example of using a valid dotted name, the following should work:

```

/**

* @namespace

*/

ns = {};

/**

* @constructor

*/

ns.someObject = function() {}

/**

* @constructor

* @augments ns.someObject

*/

otherObject = function() {}

```

Michael Mathews

mic...@gmail.com

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/QbbVWx1BAzIJ.
To post to this group, send email to jsdoc...@googlegroups.com.
To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/jsdoc-users?hl=en.

[Dan Rzeppa]

I understand. And yes I'm using JSDoc 3.

I probably should have been a little more specific in my question. I'm really trying to get things to work with RequireJS modules. After doing a little more research I see that there is some support for this with @exports tag, but I still can't get @augments to work with objects from other files.

File1 looks like:

define(function(){

  /**

  * @exports file1

  */

  var exports={}

  /**

  * @constructor

  */

  exports.someObject = function() {}

  return exports

)}

File2 looks like: 

define(function(){

  /**

  * @exports file2

  */

  var exports={}

  var file1=require("./file1")

  /**

  * @constructor

  * @augments file1.someObject

  */

  exports.otherObject = function() {}

  return exports

)}

Thanks for the help.

[Michael Mathews]

Hi Dan,

Modules? Ah! Those are a whole different kettle of fish! Sorry if I misunderstood your question, I thought you meant ordinary files.

There are some preliminary documentation on using JSDoc 3 with modules here: http://usejsdoc.org/howto-commonjs-modules.html . I am still working on those user guides but for a short answer the example you gave should work when commented like so:

```file1.js

/** @exports file1 */

define(function(){

  var exports={}

  

  /** @constructor */

  exports.someObject = function() {}

  return exports

})

```

```file2.js

/** @exports file2 */

define(function(){

  var exports = {}

  var file1 = require("./file1")

  /**

  * @constructor

  * @augments module:file1.someObject

  */

  exports.otherObject = function() {}

  return exports

})

```

Note that when referring to modules (like in your @augments tag) you need to say so, by adding the "module:" namespace before their names (unless it's in a place where it can only ever refer to a module, like after an @exports tag, and then the namespace is optional). This is because you could conceivably have a function or variable also named "file1" in the same scope, and JSDoc will always assume you mean a function or variable unless you tell it otherwise -- this is true for events as well, which require the "event:" namespace. But in any case, sorry for the confusion, and hopefully I've answered your question!

Michael Mathews

mic...@gmail.com

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.

To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/1RPgPDi5A3MJ.

[Dan Rzeppa]

That works perfectly. The confusion was all my fault. I tried to over simplify my initial question, not realizing that support for modules was already baked into JSDoc.

Thanks again for the help.