Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
  • Oct 20 20:29
    75lb labeled #259
  • Oct 20 20:29
    75lb commented #259
  • Oct 20 20:28
    75lb commented #259
  • Oct 20 18:46
    AQuackenbos edited #259
  • Oct 20 18:46
    AQuackenbos opened #259
  • Oct 17 08:57
    75lb closed #257
  • Oct 13 20:45
    martijnversluis commented #258
  • Oct 13 20:44
    75lb commented #258
  • Oct 13 20:44

    75lb on v7.1.0

    (compare)

  • Oct 13 20:44

    75lb on master

    7.1.0 (compare)

  • Oct 13 20:43

    75lb on master

    extend support back to Node.js … (compare)

  • Oct 13 20:37

    75lb on master

    Update jsdoc-api to 7.1.0 jsdo… Merge pull request #258 from ma… (compare)

  • Oct 13 20:37
    75lb closed #258
  • Oct 13 20:37
    martijnversluis commented #25
  • Oct 13 20:35
    martijnversluis opened #258
  • Oct 13 20:19
    75lb commented #25
  • Oct 13 20:18

    75lb on v7.1.0

    (compare)

  • Oct 13 20:18

    75lb on master

    7.1.0 (compare)

  • Oct 13 20:15

    75lb on master

    fix CI (compare)

  • Oct 13 20:13

    75lb on master

    extend support back to Node.js … (compare)

Ghost
@ghost~57cbaf6040f3a6eec0634f49
Hi, How can I document the below code using JSDoc?
exports.deleteAccount = function(req, res) {
   //Here is the code for delete account
}
Lloyd Brookes
@75lb
Ghost
@ghost~57cbaf6040f3a6eec0634f49
@75lb Thanks for sharing the links.
Lorenzo Romagnoli
@lorenzoromagnoli

I'm having some troubles with using a custom template. The behaviour I'm experiencing is very weird because sometimes the documentation gets correctly generated and sometimes It doesn't.

 var gulp = require( 'gulp' );

const fs = require( 'fs' )
const jsdoc2md = require( 'jsdoc-to-markdown' )



gulp.task( 'generate-doc', ( done ) => {

  var jsdocOptions = {
    files: 'library/*.js', // specify where your files are
    template: fs.readFileSync( 'docs/api-template.hbs', 'utf8' ), // read a template file
    'example-lang': 'js', // specify the "@example" code block language
    noCache: true, // Bypass caching
  }

  const output = jsdoc2md.render( jsdocOptions ).then(
    output => fs.writeFileSync( 'docs/api.md', output )
  );
  return done();
} )

This is the error I get very often

(node:88841) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): JSDOC_ERROR: The command-line option "template" requires a value.
(node:88841) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

I also tried launching the command from terminal and still get an error

$ jsdoc2md --template docs/api-template.hbs  library/mltk.js 
JSDOC_ERROR: The command-line option "template" requires a value.

It seems to work if I change the gulp file providing a string to template and then change back to the fs.readFile .
Does anyone has the the same issue or has a solution?

Lloyd Brookes
@75lb
@lorenzoromagnoli could you try deleting node_modules and package-lock.json and then running npm install from scratch please..
Ginny
@huangginny
Hi! The code base I'm working on implements class methods with arrow notations. I managed to workaround the "Unexpected token: =" by adding babel into JSDoc config, but now the docs for the methods are still not generated.
Here's my jsdoc.conf.json.
{
    "plugins": ["node_modules/jsdoc-babel"],
    "babel": {
        "presets": [
            "@babel/preset-env"
        ]
        // I also tried it with different related plugins here
    }
}
And the code looks like this
class MyClass {
    constructor(name) {
        if (!name) throw Error('No name);

        /**
         * My dependencies.
         * @type {Dependency}
         */
        this.dependencies = {};

        /**
         * My name.
         * @type {String}
         */
        this.name = name;
    }

    /**
     * @memberof MyClass
     * @function myMethodOne
     * @description
     * Internal function xxxx
     * @private
     * @param {string} name - xxxx.
     */
    myMethodOne = (name) => {
        // omit
    }

    /**
     * @memberof MyClass
     * @function myMethodTwo
     * @description
     * xxxx
     */
    myMethodTwo = () => {
        this.myMethodOne("from method two");
    }
    // and other functions, some with documentations and some without
}
The class and class properties are properly documented. Just not the methods. Thanks so much if you have any insights :)
Lloyd Brookes
@75lb
Hi @huangginny .. If your source code documentation is not parsing correctly this is usually a jsdoc issue (jsdoc-to-markdown uses jsdoc internally).. Please first ensure your source code documents correctly using jsdoc directly, before using jsdoc2md.
Lloyd Brookes
@75lb
You marked myMethodOne as @private, are you trying to declare private class field methods ?
Ginny
@huangginny
Thanks @75lb . Two things though,
  1. These docs could be generated in HTML with no problems if I use jsdoc sourceFile.js. Also jsdoc2md isn't throwing errors. The method docs are just not showing up in the resulting markdown file.
  2. I'll double check on @private but not sure if that's related. I tried taking out myMethodOne and still could not get the markdown docs generated
Ginny
@huangginny
BTW I'm on jsdoc 3.6.2 and jsdoc2md 3.0.4 which seems to be using jsdoc-75lb 3.6.0. Not sure if this piece of info helps
Lloyd Brookes
@75lb
oh, i think I might understand your issue @huangginny

Especially this line

you must use @module at the top of the file

try that.. add a @module declaration to the top of the file
Ginny
@huangginny
That doesn't work either, but I have just found that the babel transformation has caused the problem, not this tool. Thanks so much anyways!
Ginny
@huangginny
Hey sorry @75lb I have another question I'd like to ask - wondering why you use the fork "jsdoc-75lb" rather than the original "jsdoc" package.
Reason I'm asking is that jsdoc-75lb doesn't seem to allow ()=>{} function declarations in classes but jsdoc does. I tried running both jsdoc-75lb -X src.js and jsdoc -X src.js on the command line.
Lloyd Brookes
@75lb
hi @huangginny , the reason is jsdoc bugs.. or at least was.. jsdoc-75lb contains workarounds for long-standing jsdoc bugs.. the one thing that held jsdoc2md back for years was the lack of jsdoc maintenence - i alone have many jsdoc issues open
however, recently I noticed a lot of activity on the jsdoc project so I was waiting for a new release.. which I think has now landed! I will give the new version a test alongside jsdoc2md..
Ginny
@huangginny
Thanks so much! Please let me know when the new release is incorporated into jsdoc2md :)
Lloyd Brookes
@75lb
@huangginny i checked - jsdoc2md is using the latest release of jsdoc (jsdoc v4 is still in dev).. did you say you are using jsdoc2md v3.0.4? Could you upgrade please? The latest version is v5.0.3 - v3.0.4 was released in Jan 2018, it's nearly 2.5 years old..
Ginny
@huangginny
@75lb Thanks! Upgrading has somehow worked around the error showing on the console but still isn't compiling all JS docs. jsdoc -X myclass.js(jsdoc75lb 3.6.0) isn't able to read all my docs while jsdoc -X myclass.js (jsdoc 3.6.3) is.
The latter is this: https://files.gitter.im/jsdoc2md/jsdoc2md/xzTq/jsdoc-results.js The former still gives me "Unexpected tokens"
Apologies for keep badgering :joy:
Ezell
@lynellf

Hi everyone.

Anyone run into an issue when attempting to generate docs using references to other type definitions?

/**
 * @type {import("pathname").Type}
 */

I wonder what the alternatives/workarounds are.

John Winston
@winston0410
Hello everyone. jsdoc2md is not working. How can I fix this?
This is my code:
npx jsdoc2md --template README.hbs --files src/core.js
It returns the following error message
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/jsdoc2md - Not found
npm ERR! 404
npm ERR! 404 'jsdoc2md@latest' is not in the npm registry.
npm ERR! 404 You should bug the author to publish it (or use the name yourself!)
npm ERR! 404
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.
John Winston
@winston0410
Can anyone help me? I have no clue what went wrong. The version I have installed is "jsdoc-to-markdown": "^6.0.1"
Elon
@LiuWeiMr
Hi everyone
怎么实现在md文件把class的方法改为自定义的内容,比如:### signal.getGroupUserList(groupId) ⇒ <code>Promise.<PromiseReturn></code>
输出为:### 获取教室用户列表
Elon
@LiuWeiMr
注释是这样的:
/**
  • @description 获取教室用户列表
  • @param {string} groupId 群ID
  • @param {number} [limit] 查询数量
  • @param {number} [offset] 查询偏移量
  • @this Signal
  • @returns {Promise<GlobalVariable.PromiseReturn>} 用户列表或者错误原因
    */
John Winston
@winston0410
Speak English
Elon
@LiuWeiMr
How to output custom label replacement class property method.eg: class signal`s method getGroupUserList output is" signal.getGroupUserList(groupId) ⇒ <code>Promise.<PromiseReturn></code>" replease with "获取教室用户列表"
GrahamSH
@GrahamSH-LLK
When I run jsdoc2md -t "API.hbs" "./addon-api/*/*.js" > "api.md" locally, it works, but when I run it in github actions, I get JSDOC_ERROR: The command-line option "template" requires a value.
Daniel McCormack
@dmccormack3
I have documented my TypeScript Classes using JSDoc. When I run jsdoc2md it only outputs the documentation for the classes, not the functions within the classes (which are also documented). The JSDoc compiler picks these up, but the jsdoc2md is not. Is there a configuration option I am missing? Thanks.
/**
 * Class for the user (this doc is output)
 * @hideconstructor
 */
@Injectable()
export class CurrentUserApiService{

    /**
     * Gets the object containing the users details (this isn't output)
     * @returns  The users current details
     */
    private getUserDetails = () : any => {
        return [];
    }
}
Daniel McCormack
@dmccormack3

Looks like my above issue is due to the "fat arrow" functions. If I change it to it works. Perhaps an issue with the babel transpiler?

private getUserDetails() : any { return []; }

Daniel McCormack
@dmccormack3
@huangginny Did you manage to fix your issues using arrow functions? I can't get documentation to generate for class arrow functions. E.G.
private getUserDetails = () : any => { return []; }
Maarten Coppens
@maarteNNNN
Is there a way to get more verbose errors?
I get this error but I can't seem to find it in the repository
JSDOC_ERROR: Jsdoc failed.
I tried deleting the JSDocs function by function to see if there was a bug inside the JSDocs I created but it still shows the same error
generating JSDocs with the jsdoc package runs perfectly
Jordan Dalton
@TGRHavoc
I'm having the same issue as @GrahamSH-LLK . It seems that JSDoc (the jsdocApi.explain function more specifically) wants the "template" property to be a filename string but, "dmd" wants it to be the actual template string (e.g. {{>main}}). I was able to get it working again by doing some changes. I had to change cli.js line 72 to if (options.template) options.renderedTemplate = fs.readFileSync(options.template, 'utf8') then dmd-options.js to include the line this.template = options.renderedTemplate;.
Was wondering if this issue had already been fixed in the more recent versions (i'm stuck on 6.0.1 because I'm in an environment that won't allow a more recent node version) even though those lines seem to be unchanged (maybe a dependency update fixed it?)
Jordan Dalton
@TGRHavoc
Okay, so it seems the latest version (7.0.1) does indeed fix the above issue. Just managed to get the latest node version installed and jsdoc2md 7.0.1
Leif Olsen
@leifoolsen

Hi all.

We need to document functions and React hooks in our Storybook setup. In that context, we need to be able to generate one MarkDown file per JS file. According to "jsdoc2md/jsdoc-to-markdown#95" this is not a priority in jsdoc2md.

If others have the same needs, you can use the following script to solve this:

const {basename, extname, join, resolve} = require('path');
const {readdirSync, statSync, writeFileSync} = require('fs');
const jsdoc2md = require('jsdoc-to-markdown');

const root = resolve(process.cwd());
const sources = [
  {
    src: join(root, 'packages/brreg-frontend-utils-js/src'),
    dest: join(root, 'packages/brreg-frontend-utils-js/src/__stories__'),
    exclude: ['index.js']
  },
  {
    src: join(root, 'packages/brreg-frontend-use-portal-node-react/src'),
    dest: join(root, 'packages/brreg-frontend-use-portal-node-react/src/__stories__'),
    exclude: ['index.js']
  }
];

/**
 * Find all files recursively, with a given extension, e.g:
 * findFiles('./project/src', '.js') ==> ['./project/src/a.js','./project/src/build/index.js']
 *
 * @param {String} startPath Path relative to this file or other file which requires this files
 * @param {String} ext Extension name, e.g: '.js'
 * @param {Boolean} recursive Whether to scan sub directories for files
 * @returns {Array<string>} Result files with path string in an array
 * @see https://www.codota.com/code/javascript/modules/jsdoc-to-markdown
 */
const findFiles = (startPath, ext, recursive = false) => {
  let result = [];
  const regex = new RegExp(`\\${ext}$`)
  const files = readdirSync(startPath);

  for (let i = 0; i < files.length; i += 1) {
    const file = join(startPath, files[i]);
    if (statSync(file).isDirectory()) {
      if (recursive) {
        try {
          result = result.concat(findFiles(file, ext));
        }
        catch (error) {
          console.error(error); // eslint-disable-line no-console
        }
      }
    }
    else if (regex.test(file)) {
      result.push(file);
    }
  }
  return result;
}

/**
 * Make JSDoc for a given source folder
 *
 * @param {string} src Source folder with *.js files to generate MD for
 * @param {string} dest Destination folder for generated MD
 * @param {string[]} exclude Array of files to exclude
 */
const makeJSDocFor = (src, dest, exclude = []) => {
  const jsFiles =  findFiles(src, '.js');

  console.log('Make JSDoc: ', src); // eslint-disable-line no-console
  for (let i = 0; i < jsFiles.length; i += 1) {
    if (exclude.find((arg) => jsFiles[i].endsWith(arg))) {
      continue;
    }
    const newContent = jsdoc2md.renderSync({files: jsFiles[i]});
    const ext = extname(jsFiles[i]);
    const outputFile = basename(jsFiles[i], ext);
    writeFileSync(join(dest, `${outputFile}.md`), newContent, 'utf8');
    // console.log('Make JSDoc:', jsFiles[i], '->', join(dest, `${outputFile}.md`)); // eslint-disable-line no-console
  }
  console.log('Make JSDoc: Updated', jsFiles.length, `file${jsFiles.length > 1 ? 's' : ''} in`, dest); // eslint-disable-line no-console
}

/**
 * Make JSDoc
 */
function makeJSDoc() {
  for (const {src, dest, exclude} of sources) {
    makeJSDocFor(src, dest, exclude);
  }
}

makeJSDoc();

With the following setup in Storybook, we can create a nice API documentation per JS file.

import {Description, Meta, Story} from '@ storybook / addon-docs / blocks';
import hashcodeMD from './hashcode.md'

<Meta
   title = "Utils / Utils / Misc"
   parameters = {{
     viewMode: 'docs',
   }}
/>

<Story name = "hashcode">
   {() => (<Description> {hashcodeMD} </Description>)}
</Story>
Jean-Philippe Côté
@djipco

I'm not sure why but when I use the syntax below, I get empty output:

/**
 * Test...
 */
export class Input { }

However, if I use this syntax, it works fine:

/**
 * Test...
 */
class Input { }

Is there a way to keep the export and get some output?