Skip to content

polyglot gives me a blank documentation #26

Open
@vwochnik

Description

@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.

Activity

tmcw

tmcw commented on Dec 1, 2016

@tmcw
Member

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

vwochnik commented on Dec 1, 2016

@vwochnik
Author

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

tmcw commented on Dec 1, 2016

@tmcw
Member

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

vwochnik

vwochnik commented on Dec 1, 2016

@vwochnik
Author

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

tmcw commented on Dec 1, 2016

@tmcw
Member

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

vwochnik commented on Dec 1, 2016

@vwochnik
Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @tmcw@vwochnik

        Issue actions

          `polyglot` gives me a blank documentation · Issue #26 · documentationjs/gulp-documentation