ReferenceError: $ is not defined

[blaasvaer]

Due to a »complex« system I load libraries from elsewhere besides node_modules.

I reference the DOM from modules with $ (jQuery) without any issues.

But gulp-jsdoc3 doesn't seem to like this, it throws errors:
ReferenceError: $ is not defined

How can I suppres gulp-jsdoc3 from doing this?

[mlucool]

Where does it do this? Can you paste the whole error? In general gulp-jsdoc3 does not run any of your code.

[blaasvaer]

Well, after closing all apps and restarting the computer, that error went away.
But I'm still only getting empty directories:

This is what I have in my gulpfile.js:

gulp.task('docs', function (cb) {
    var documentation_src = './src/admin/node_modules/**/*.js';

    gulp.src( ['README.md', documentation_src], { read : false } )
        .pipe( jsdoc3( cb ) )
        .pipe( gulp.dest( './docs3' ) );
});

But all I get is a directory named »docs3« as defined in the src destination, containing empty directories named after each module ... nothing else.

If I remove the { read : false } and the »README.md« parts, having this:

gulp.task('docs', function (cb) {
var documentation_src = './src/admin/node_modules/**/*.js';
gulp.src( documentation_src )
    .pipe( jsdoc3( cb ) )
    .pipe( gulp.dest( './docs3' ) );

});

I get directories containing the module themselves ('index.js' files).

I'm having a hard time finding any valuable documentation on how to use this module.

The original gulp-jsdoc runs fine, even though not maintained anymore ...

[AndrewGuenther]

@blaasvaer Do not use the gulp.dest directive with this module. Your documentation is being output in a folder called docs/gen.

I agree that that definitely isn't clear from the README documentation. I can submit a PR to update it.

[blaasvaer]

If that's the case, then you should definitely make a note of that.

I would expect to have control over where to output my docs ... and if that's a setting in some arbitrary config file, then that should be noted as well (even a complete config example file).

Please, provide thorough documentation when putting code out there. Assume as little as possible. There may be people totally new to this whole thing that may spend hours or even days trying to figure things out merely by guessing.

But thanks for pointing it out.

[AndrewGuenther]

I mean, I'm not the maintainer, I just took 5 minutes to look at the source code. Not "hours" or "days."

Cheekiness aside, I'm happy to contribute a more thorough README.

[blaasvaer]

Imagine everyone skipping documentation, and just ask people to read the fucking code (RTFC) : ) ...

But thanks anyway.

[AndrewGuenther]

There source is documented. Right at the top. Just open the file.

[blaasvaer]

Thanks, but where exactly does it state that it outputs to docs/gen?

[AndrewGuenther]

Default value for config is require('./jsdocConfig.json') which exists in the same directory and has the value

 "opts": {
    "destination": "./docs/gen"
  },

Again, I agree that putting this information in the README would be useful, but it definitely isn't hard to find.

[blaasvaer]

OK, totally missed that one, even when looking for it. Well, that just proves my point I guess ... ; )

[blaasvaer]

And you're right, not hard to find at all, if you know what you're looking for (I couldn't). The problem with a thing like this is, that basically everything I do in gulp is pass in a src and define a destination. And on top of that, it even used to be like that with the old jsdoc. Now comes a new kid along, and decides to remove the destination (from gulp itself at my end), and put it into a config file – not making any note of it, and then expect people to go read the code to find that information.

When you base a project on some previous project (at least that's the impression I get), you should thoroughly point out where you have made fundamental changes to stuff. Otherwise we end up having someone like me write all this crap I'm doing at the moment.

This is what it used to be like with gulp-jsdoc:

 gulp.src( documentation_src )
 .pipe( jsdoc( 'docs' ) )
 .pipe( jsdoc.parser( infos, name ) )
 .pipe( gulp.dest( './docs' ) );

So yes, please help making a better documentation if possible. And thank you for all your help.

[blaasvaer]

I guess they have tried to somehow communicate it here by this comment in the notes:

It also does not pass on output to be piped elsewhere.

But I'm not sure it'll get the message passed on properly.

[AndrewGuenther]

A little background, gulp-jsdoc was an unmaintainable mess which depended deeply on private internal jsdoc APIs. This version does not make that mistake, and is a totally independent implementation from gulp-jsdoc.

I think having a migration guide pointing out the differences would be worth while, I can add that as well. If there are features you'd like to see, please submit a feature request rather than stating how things "should" work.

[blaasvaer]

Point taken, and totally agree. Thanks.

[mlucool]

Thanks for working through this @AndrewGuenther - all readme changes were merged and a new release is out. Any other changes here or should I close this thread?

[blaasvaer]

Way better now, thanks a lot. : )