Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
  • Feb 26 23:15

    75lb on master

    deps (compare)

  • Feb 26 23:11

    75lb on v6.0.0

    (compare)

  • Feb 26 23:11

    75lb on master

    6.0.0 (compare)

  • Feb 26 23:11

    75lb on master

    drop support for node < v14.. u… (compare)

  • Feb 26 23:07
    75lb closed #221
  • Feb 26 23:07
    75lb commented #221
  • Feb 26 23:04
    75lb closed #230
  • Feb 26 23:04
    75lb commented #222
  • Feb 26 23:00
    75lb commented #225
  • Feb 26 22:58
    75lb labeled #229
  • Feb 26 22:56
    75lb commented #230
  • Feb 26 22:53
    75lb closed #231
  • Feb 26 22:53
    75lb commented #231
  • Feb 26 22:52

    75lb on v7.0.0

    (compare)

  • Feb 26 22:52

    75lb on master

    7.0.0 (compare)

  • Feb 26 22:46

    75lb on master

    drop support for node < v14.. u… (compare)

  • Feb 26 22:43

    75lb on v7.0.0

    (compare)

  • Feb 26 22:43

    75lb on master

    7.0.0 (compare)

  • Feb 26 22:41

    75lb on master

    drop support for node < v14.. u… (compare)

  • Feb 26 22:38

    75lb on v6.0.0

    (compare)

Lloyd Brookes
@75lb
@Favna i'm sorry, believe it or not I have no experience using jsdoc2md to document Typescript.. There is a community-authored page on the subject here but I can't vouch for its accuracy.. There's a jsdoc issue about documenting Typescript here: jsdoc3/jsdoc#272.
Jeroen Claassens
@Favna
Guess I'll just have to keep struggling through trial and error. I've gone through the wiki page but that hasn't helped me so far and the info on the issue isn't a lot I haven't tried yet.
Lloyd Brookes
@75lb
@Favna ok.. sorry about the struggle.. feel free to edit the wiki if you think you can improve it.
Jeroen Claassens
@Favna

well the plot thickens is all I can say @75lb . From command line it quite consistently works, I will be editing the community page you linked since it has some mistakes.

From Gulp it's ..well... it's odd. Sometimes it does work and sometimes it doesn't. For now I've ran my task like 10x already and all went okay but whether that is to stay, I don't know. If it does I'll add it to the community page about using Gulp.

Jeroen Claassens
@Favna
Update: Edited the typescript wiki page and the Gulp wiki page
Jeroen Claassens
@Favna

@75lb since I was going around the wiki anyway I

  1. created a custom side bar linking to all currently existing pages which offers easier navigation since users don't have to expand the pages with show 11 more pages... anymore now and it's all nicely tidied up as well. By proxy I renamed a few pages so they are better fitting in their categories.

  2. copied all but coverage and build status badges from the readme to the footer so that's all fancied up as well. (not those 2 coz then it would be across 2 lines which is ugly again)

Lloyd Brookes
@75lb
thanks for the wiki improvements @Favna ! Looks decent.. jsdoc2md will get a maintenance push at some point.. i'll be honest, the lack of upstream jsdoc maintenance (many outstanding issues/PRs including bugs directly affecting jsdoc2md) has been a concern for a while.. the next major jsdoc2md release will be almost certainly decoupled from jsdoc.
Lloyd Brookes
@75lb
maybe i'll define a data model that jsdoc2md can consume and generate docs from.. obv the first generator created will be one that parses jsdoc comments (as current behaviour) but any tool capable of generating data meeting the defined spec could become a jsdoc2md input.. hopefully, the model could be trivial enough to hand-roll using yaml, if required..
a major blocker to contribution has been handlebars.. getting to know the templates/partials/helpers is just too much work for casual contribution - handlebars will definitely get the boot..
anyway, stuff for the future..
dimtabu
@taburetkin

struggling with generating md.
i have some public method and i want to document it.

function someMethod(...args) { ... }

And its actual valid signatures are :
someMethod(string, function, [object])
someMethod(object, [function], [object])
how to correctly describe this?

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.