JSDoc output inconsistent between gulp-jsdoc & standard CLI - jsdoc

I'm trying to build docs for a simple set of JS code (given below). If I use gulp, the docs are created how I would expect them. If I use the CLI, the docs are incomplete.
Here's my JS code:
// BASE.js
/** #module BASE */
var BASE = {};
// MOD1.js
/** #class MOD1 - Test module */
BASE.MOD1 = Object.create({});
/**
* Just a test function
* #param {Object} var1 - A test variable
*/
BASE.MOD1.testFunction = function(var1){
alert('hi');
};
My gulp file:
var gulp = require('gulp'),
jsdoc = require('gulp-jsdoc'),
outDir = './gulp-docs/',
docInfo = {},
docOptions = {},
docTemplate = {},
srcFiles = [
"BASE.js",
"MOD1.js"
];
gulp.task('default', function() {
return gulp.src(srcFiles)
.pipe(jsdoc.parser(docInfo))
.pipe(jsdoc.generator(outDir, docTemplate, docOptions))
});
And my command line:
C:\DocTest> jsdoc BASE.js MOD1.js --configure rawconf.json --destination raw-docs
rawconf.json:
{
"tags": {
"allowUnknownTags": true
},
"plugins": [],
"templates": {},
"opts": {
"package": "./rawpackage.json"
}
}
rawpackage.json:
{}
I run both gulp and the jsdoc command from the Node.js command prompt.
Output from gulp is the following files:
BASE.js.html
BASE.MOD1.html
index.html
MOD1.js.html
module-BASE.html
Output from the CLI is the following files:
BASE.js.html
index.html
MOD1.js.html
module-BASE.html
module-BASE-BASE.MOD1.html
There are some small differences which I can chalk up to the differences between the gulp-jsoc version of jsdoc (3.3.0-alpha5) and the current version (3.3.0-beta3).
But the biggest difference is that while in the gulp output, I can find information on testFunction, there is no information to be found at all regarding testFunction anywhere in the CLI output. I've even searched the HTML code--nothing.
So did I do something wrong? I'm just trying to achieve parity at this point, and I've exhausted any documentation I could find online.

If you look at the gulp-jsdoc github page here, there's a "Big Fat Warning" that this plugin isn't being kept up to date.
Try using the gulp-shell plugin. You can use exactly what you typed into the command line.

Related

Getting this error with the #metaplex-foundation/js-next SDK

Currently working on a react app and I'm getting this error after installing metaplex.
My react-scripts version is 4.0.3
./node_modules/#metaplex-foundation/js-next/dist/esm/programs/token/gpaBuilders/TokenGpaBuilder.mjs
Can't import the named export 'ACCOUNT_SIZE' from non EcmaScript module (only default export is available)
I found out the solution in the git of metaplex here. I will leave you here the whole answer anyway.
Getting Started with Metaplex and CRA 5
This example sets up a new React app with Metaplex using "Create React App" (CRA) version 5 — i.e. using Webpack 5.
This example has been generated using the following steps:
Create a new project using the "Create React App" command.
npx create-react-app getting-started-react-cra5
cd getting-started-react-cra5
Install the Metaplex and the Solana SDKs.
npm install #metaplex-foundation/js #solana/web3.js
Install some polyfills.
npm install assert util crypto-browserify stream-browserify
Install and use react-app-rewired.
# Installs react-app-rewired.
npm install react-app-rewired
# Replaces "react-scripts" with "react-app-rewired" in package.json scripts.
sed -i '' 's/react-scripts /react-app-rewired /g' package.json
Override Webpack 5 configurations.
Create a new file to override Webpack 5 configurations.
touch config-overrides.js
Copy the following code inside the new config-overrides.js file.
const webpack = require("webpack");
module.exports = function override(webpackConfig) {
// Disable resolving ESM paths as fully specified.
// See: https://github.com/webpack/webpack/issues/11467#issuecomment-691873586
webpackConfig.module.rules.push({
test: /\.m?js/,
resolve: {
fullySpecified: false,
},
});
// Ignore source map warnings from node_modules.
// See: https://github.com/facebook/create-react-app/pull/11752
webpackConfig.ignoreWarnings = [/Failed to parse source map/];
// Polyfill Buffer.
webpackConfig.plugins.push(
new webpack.ProvidePlugin({ Buffer: ["buffer", "Buffer"] })
);
// Polyfill other modules.
webpackConfig.resolve.fallback = {
crypto: require.resolve("crypto-browserify"),
stream: require.resolve("stream-browserify"),
util: require.resolve("util"),
assert: require.resolve("assert"),
fs: false,
process: false,
path: false,
zlib: false,
};
return webpackConfig;
};
Update your browser requirements.
Update the browserslist object of your package.json to include the following production requirements.
"browserslist": {
"production": [
- ">0.2%",
- "not dead",
- "not op_mini all"
+ "chrome >= 67",
+ "edge >= 79",
+ "firefox >= 68",
+ "opera >= 54",
+ "safari >= 14"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
},
That's it!
You should not use #metaplex-foundation/js-next SDK, the actual repo is #metaplex-foundation/js, the name was changed and the updated repo is this, so try using #metaplex-foundation/js instead

Jest: Cannot use import statement outside a module

I got an error when I run test using Jest, I tried to fix this error for 2 hours. But, I couldn't fix it. My module is using gapi-script package and error is occurred in this package. However, I don't know why this is occurred and how to fix it.
jest.config.js
module.exports = {
"collectCoverage": true,
"rootDir": "./",
"testRegex": "__tests__/.+\\.test\\.js",
"transform": {
'^.+\\.js?$': "babel-jest"
},
"moduleFileExtensions": ["js"],
"moduleDirectories": [
"node_modules",
"lib"
]
}
babel.config.js
module.exports = {
presets: [
'#babel/preset-env',
]
};
methods.test.js
import methods, { typeToActions } from '../lib/methods';
methods.js
import { gapi } from "gapi-script";
...
Error Message
C:\haram\github\react-youtube-data-api\node_modules\gapi-script\index.js:1
({"Object.":function(module,exports,require,__dirname,__filename,global,jest){import
{ gapi, gapiComplete } from './gapiScript';
SyntaxError: Cannot use import statement outside a module
What is wrong with my setting?
As of this writing, Jest is in the process of providing support for ES6 modules. You can track the progress here:
https://jestjs.io/docs/en/ecmascript-modules
For now, you can eliminate this error by running this command:
node --experimental-vm-modules node_modules/.bin/jest
instead of simply:
jest
Be sure to check the link before using this solution.
I solved this with the help of Paulo Coghi's answer to another question -
Does Jest support ES6 import/export?
Step 1:
Add your test environment to .babelrc in the root of your project:
{
"env": {
"test": {
"plugins": ["#babel/plugin-transform-modules-commonjs"]
}
}
}
Step 2:
Install the ECMAScript 6 transform plugin:
npm install --save-dev #babel/plugin-transform-modules-commonjs
Jest needs babel to work with modules.
For the testing alone, you do not need jest.config.js, just name the testfiles xxx.spec.js or xxx.test.js or put the files in a folder named test.
I use this babel.config.js:
module.exports = function (api) {
api.cache(true)
const presets = [
"#babel/preset-env"
]
return {
presets
}
}
Adding "type": "module" in package.json or using mjs as stated in other answers is not necessary when your setup is not too complicated.
I have also faced the same issue and this was resolved by adding following command-line option as a environment variable.
export NODE_OPTIONS=--experimental-vm-modules npx jest //linux
setx NODE_OPTIONS "--experimental-vm-modules npx jest" //windows
Upgrading Jest (package.json) to version 29 (latest as of now) solved this problem for me.

Babel preset es2015 loose not working?

Is this "loose": true not working for the "es2015" preset or a mistake/misunderstanding on my part?
Input Code
I've tried with the REPL and on on the command line. I can't get babel to translate my loose javascript in looseWith.js:
var obj = {};
with (obj) {
}
.babelrc (attempt1):
{
"presets": [
[ "es2015", { "loose": true }]
]
}
.babelrc (attempt2 - as in REPL):
{
"presets": [
"es2015-loose"
]
}
I then try running either of these .babelrcs:
> babel looseWith.js
SyntaxError: looseWith.js: 'with' in strict mode (2:0)
1 | var obj = {};
> 2 | with (obj) {
| ^
3 | }
Seems to me that this is still in strict mode. The documentation on loose is quite scarce and just says:
Enable "loose" transformations for any plugins in this preset that allow them.
I'm trying to negate use strict :-) Is this my misunderstanding? What other meanings are there for "loose"?
I then tried adding "modules": "umd" to .babelrc to attempt1 above, and when fed with a proper strict .js file, it did produce umd output, so I think babel is picking up the .babelrcmodule just fine.
Background
I'm trying to be able to use ES6 in my underscore/lodash templates. The javascript output of e.g. _.template(script).source contains the "with" statement (by default). So I'm trying to use babel to translate ES6 - including the "with" statement - into ES5.
Environment
> node --version
v7.10.1
> cat package.json
{
"dependencies": {
"babel-cli": "^6.24.1",
"babel-core": "^6.25.0",
"babel-preset-es2015": "^6.24.1",
"babel-preset-es2015-loose": "^8.0.0"
}
}

Karma preprocessor not running

My karma.conf.js includes:
plugins: [
'karma-jasmine',
'karma-phantomjs-launcher',
'karma-ng-html2js-preprocessor'
],
preprocessors: {
'../../mypath/*.html': ['ng-html2js']
},
ngHtml2JsPreprocessor: {
moduleName: 'templates'
},
(I've tried without specifying any plugins, too.)
My devDependencies include:
"karma-ng-html2js-preprocessor": "^0.2.0"`
My tests include:
beforeEach(module('templates'));
These give the error:
Module 'templates' is not available!
Running karma with --log-level debug, I do not see any [preprocessor.html2js] entries. (I do get Loading plugin karma-ng-html2js-preprocessor.)
What am I doing wrong?
The issues were that the templates must be listed under files as well, and that the glob pattern in preprocessors must match. This is implied by the documentation.
files: [
'../../Scripts/angular-app/directives/*.html',
// .js files
],
preprocessors: {
'../../Scripts/angular-app/**/*.html': ['ng-html2js']
},
Note that **/*.html does not match parent directories of the basePath.
karma start --log-level debug will display DEBUG [preprocessor.html2js] entries when everything is correct.
I was also able to remove the plugins section.
To get the correct cache ID, I used:
ngHtml2JsPreprocessor: {
// Load this module in your tests of directives that have a templateUrl.
moduleName: 'templates',
cacheIdFromPath: function (filepath) {
return filepath.substring(filepath.indexOf('/Scripts/angular-app/'));
}
},
If a template references a custom filter, the filter must be loaded in files and the filter's module must be loaded in your directive tests.

r.js throws an error every time I try to assign a variable in Coffee-Script

So I'm using r.js to build a bunch of my files -- some of which are Coffee-Script. I am using the Require plugin require-cs to handle this.
Here is a look at my Require.js config, a la rjs:
rjs.optimize({
baseUrl: SRC_PATH,
include: channelMap[channel],
optimize: 'none',
stubModules: ['cs', 'tpl', 'less', 'text'],
exclude: ['normalize', 'coffee-script', 'underscore'],
CoffeeScript: {
header: false,
// since we use AMD, there's no need for IIFE
bare: true
},
separateCSS: true,
skipModuleInsertion: true,
// If something needs to be present for tests too and not only for
// the build step, then add it tools/karma-amd.js instead
paths: _.extend({
'less-builder': 'vendor/require-less/less-builder',
'normalize': 'vendor/require-less/normalize'
}, rjsPaths),
wrap: true,
less: {
paths: [path.join(BASE_SHOP_FOLDER, 'static', 'zalando', 'css', channel)]
},
out: path.join(BUILD_PATH, channel, BUILD_BASE_FILE_NAME + '.js')
}, function () {
// this needs to be async because less builder uses
// process.nextTick() to write the file
process.nextTick(done);
});
Even the most simple .coffee file seems to fail violently. E.g.
define [], ->
foo = "hello world"
return foo
throws the following error:
the variable "foo" can't be assigned with undefined because it has not been declared before
foo = "hello world"
^^^
When I use replace require-cs's coffee-script.js with the older version of 1.6.3 everything works just fine.
Your code compiles BTW. Try to go to CoffeeScriptDahWebSite and click on TRY COFFEESCRIPT and you will see that it is valid code.
From the define [], () -> code ..., I assume you are using the CoffeeScript plugin with require.js. I am ready to bet your issue is in the require.js configuration (which should be your main.js file or whatever you named it) since the error you get looks oddly like the JavaScript interpreter trying to run the invalid code you wrote (for JavaScript that is :). Meaning, your plugin is not there at all.
If you give me your require configuration maybe I can edit this answer and help you more.
Cheers!
EDIT
I see you edited your question, but you provided me the wrong file. What you showed me was the r.js optimizer configuration, instead of the main.js which specifies how cs.js and coffee-script.js files are loaded. The error might be in your optimizer, but I can't know without seeing your other config.
A reiteration of that, show me the entry point of your program, the data-main that is loaded in your HTML.
I was unable to recreate the issue:
$ cat ./etc/temp1.coffee
define [], ->
foo = "hello world"
return foo
$ coffee --version
CoffeeScript version 1.7.1
$ which coffee
/home/dev/.nvm/v0.10.23/bin/coffee
$ coffee -cp ./etc/temp1.coffee
// Generated by CoffeeScript 1.7.1
(function() {
define([], function() {
var foo;
foo = "hello world";
return foo;
});
}).call(this);
$ coffee -cpb ./etc/temp1.coffee
// Generated by CoffeeScript 1.7.1
define([], function() {
var foo;
foo = "hello world";
return foo;
});
Turns out the problem was with my previous version of 1.7.1. Someone Beautified it and broke everything. Everything works as advertised when I go out of my way to get coffee-script.js from http://coffeescript.org/extras/coffee-script.js