polyglot gives me a blank documentation

[vwochnik]

I have the following configuration in my gulpfile.js:

gulp.task("docs", function() {
  gulp.src("src/**/*.js")
    .pipe(documentation('html', { shallow: true }, {
      name: pkg.name,
      version: pkg.version
    }))
    .pipe(gulp.dest("dist/docs"));
});

When I add polyglot: true after the shallow: true, the generated documentation becomes blank. I do not want the JavaScript to be analyzed.

One particular reason is that overloaded functions have a lot of argN: any at the end if you leave it out in the documentation.

[tmcw]

I'm confused: are you trying to document JavaScript? If you'd like to turn off inference, there's a troubleshooting topic for that - the gist is to use the name tag to turn off inference in a standard way.

[vwochnik]

Well, for gulp-documentation this is off-topic, but the main issue is this:

/**
 * getter
 * @param {string} name var name
 * @return {any} value
 */
/**
 * setter
 * @param {string} name var name
 * @param {any} value value to set
 * @param {integer} param1 first parameter
 * @param {integer} param2 second parameter
 * @return {any} value
 */
function test(name, value, param1, param2) {
  if (arguments.length > 1) {
    // set stuff
  }

  // get stuff
}

Now, when you generate the documentation, you get the following function definitions within the generated HTML:

// getter ( I don't want the variables to show up here )
test(name: string, value: any, param1: any, param2: any)
// setter
test(name: string, value: any, param1: integer, param2: integer)

It is simply inaccurate to have the definition of the getter.

[tmcw]

Can you try using @name test to avoid inference in this case?

[vwochnik]

That might be possible, yes. But on the other hand, then I'll be losing that object methods are always in a tree-like fashion below the object.

Also, with @name, I suddenly have no argument list behind the method. Wouldn't it be possible to generate an argument list from the @params given? Also, overloaded constructors cause a whole class with all methods to be listed twice, not just the constructor.

[tmcw]

You can use the @memberof tag to add the tree structuring. Right now that's basically how this works: you can have inference, or you can turn it off, for a file with polyglot or for a function with @name - there's no way to just infer membership but not params or type, etc - at this point. That functionality is planned, and if you'd like to expedite it, I'd happily accept a PR.

I'll see if a test case can confirm the loss of parameter lists for this example. That might be because there's no @function tag either - re previous paragraph, that's also something that's inferred, so if you turn off inference, you'll need to declare types manually.

[vwochnik]

Wow thank you! This worked perfectly. Now my only problem is that overloaded constructor will re-create the same class with all members twice.

I have tried adding a @name and @class tag but still - classes with same name are created twice.