Replace JSDoc as it is not maintained and is legacy software #1089

ShukantPal · 2022-03-19T23:21:57Z

Hi folks, JSDoc is no longer being actively maintained and that's why I built a better, maintainable toolset called webdoc. webdoc has a more modern theme that's fully customizable! I would be down to helping you move your documentation to webdoc, the choice is up to you.

I think webdoc will bring a lot of clarity to your existing documentation, and it is pretty good for this use case. See the PixiJS (also a renderer) documentation site: https://api.pixijs.io

obiot · 2022-03-21T01:05:45Z

hi, thanks for reaching out !

we have been discussing this actually for years (literally #497) but nobody never took on the task, as honestly it does look like a big one, maybe not anymore in "converting" the tags, but especially in recreating a specific template/theme and all.... but definitely, If you are willing to help, I could hardly say now :)

ShukantPal · 2022-03-21T04:16:31Z

Ok will take a look next weekend.

doc generation currently failing !

obiot · 2022-06-01T03:27:44Z

Hi @ShukantPal, I went ahead and added a npm task to generate webdoc documentation, but it's not as straightforward as you were implying though.

So first comments and related questions :

I literally have a billions of [...] does not have a "-" token preceeding description [...] errors : is there a way to configure this ? this was not an issue with jsdoc, and I really don't feel like going through all the source code to add a - between each function parameter and their description
is it possible to output the line number where the tag parsing error is coming from ?
I use this "trick" (https://github.com/melonjs/melonJS/blob/master/src/geometries/line.js#L15-L31) to generate different doc entry for the same function when the function takes different parameters, but webdoc does not seem to like it (e.g. "x" is not a parameter & cannot come after the last parameter "), is there a way to disable warning or force it, similarly to eslint for example ?
what are the [DepsChain] xxxx is a member of xxxx output for ?
every time I run webdoc it creates an example.api.json file at root level ?

thanks !

Note: I'm using the default template for now ("@webdoc/default-template"), config file is here : https://github.com/melonjs/melonJS/blob/master/webdoc.conf.json

ShukantPal · 2022-06-01T05:07:00Z

I'll create an option to disable these warnings & try to release this weekend. I don't think there's a way to disable it immediately.
Can you post which error you're seeing in this case?
Hmm I didn't think of this use case when I added that guard. I can create an option to disable all of these checks.

Unlike JSDoc, webdoc uses a tree structure to model your symbolic relations. This means if C is a member of B and B is a member of A, you can't declare A to be a member of C (a cyclical child-parent relationship). If you're seeing this log, then it's probably a violation of this requirement.
Yes, you can set the opts.export option to rename it to melon.api.json

"opts": {
  "export": "melon.api.json" // or false if you don't like it, but please don't :)
}

This api.json manifest is a serialization of webdoc's model for your symbol tree. At the moment, it can be used to import a project's API documentation in another place. For example, if someone created a MelonJS plugin and wanted to document a class that extends a class in Melon - they could import your api.json manifest by it's URL and webdoc would be able to correctly link references to MelonJS symbols on their website to the MelonJS documentation website.

obiot · 2022-06-01T07:00:06Z

thanks for the quick feedback !

I'll wait for this weekend then for your update so that at least it can fix most of the issue on point 1 and 3, feel free to clone the repo on your side and give it a look (use npm run webdoc for now, I will replace jsdoc properly once all done).

for the manifest, got it, I'll then move it to where the doc is generated (dist/doc).

obiot · 2022-06-01T07:03:31Z

for the error report, for example when running the eslint jsdoc plugin, it gives me this :
ERROR: The @publiec tag is not a known tag. File: deprecated.js, line: 62

would be a nice addition as well to have that plugin (or a similar one) also being compatible with the syntax/tags expected by webdoc !

obiot · 2022-06-01T07:07:36Z

and here is the full log :webdoc_error.log

obiot · 2022-06-01T07:12:19Z

oh, and one last thing I noticed is that a comment section with the tag @ignore or even no tag at all, is reported as an error. both should just do nothing/fail silently (like jsdoc) or worst case gives a warning

obiot · 2022-06-05T08:43:41Z

for the record, and for future discussion about template, I moved the jsdoc one we currerntly use into its own repo here: https://github.com/melonjs/jsdoc-template

ShukantPal · 2022-06-05T20:21:59Z

I cloned melonJS locally. The [DepsChain] errors are because webdoc doesn't understand @memberof Renderer.prototype - it expects @memberof Renderer. I think JSDoc also supports this syntax, is it okay if I make a PR on melonJS for this specific issue? (still fixing the other stuff in webdoc :))

obiot · 2022-06-06T00:26:31Z

Definitely! Please do 🙏🙏🙏

ShukantPal · 2022-06-06T00:43:01Z

@obiot I've released webdoc 1.6.0 with some fixes for your codebase: https://github.com/webdoc-labs/webdoc/releases/tag/v1.6.0. You can pass the --quiet option to suppress the unwanted tag parser warnings!

There are some parsing failures - some because of webdoc, and some because of melonJS incorrectly documenting symbols. The documentation site is still getting generated, just with some of those omissions.

Examples of the latter are where you're declaring members above if statements. webdoc doesn't know what you're documenting and there isn't any @member / @name tag, neither is it above a this. property assignment.

I can fix this with either option. I can make a PR for these errors (they're not that frequent).

Option 1	Option 2

Here are the problems on webdoc's side I'll be working on this week:

Parsing the enum in keyboard.js from the source. For some reason, it's not parsing the enum properties correctly.
Method overloads. They work in TypeScript but not with the JSDoc notation - I'll look into why.
Displaying the parameter table for standalone function pages.

You can generate the doc site locally and see if there's anything that needs to be corrected and I'll add them to this list (feel free to create issues at webdoc-labs/webdoc)

obiot · 2022-06-06T00:55:36Z

Hi @ShukantPal, that's awesome ! I'll update and work on it as well this week; also definitely you spotted them, there are some quirky jsdoc tags that need to be fixed. I already spent some times few months ago cleaning/unifying everything and moving to a more jsdoc es6 class approach (for the melonJS 2 release), but we still do have some weird stuff here and there.

obiot · 2022-06-06T01:03:22Z

by the way, did you already added the possibility to have a different delimiter between argument names and descriptions ? I was looking at your commits this weekend, but I don't think I saw it.

I mean the one for :
[TagParser]:{@TMXRenderer.drawTile} Parameter "renderer" does not have a "-" token preceeding description <a renderer object>

ShukantPal · 2022-06-06T01:04:35Z

@obiot
You just need to pass --quiet here 😃:

melonJS/package.json

Line 98 in 927b12d

"webdoc": "mkdirp dist && webdoc -R README.md",

The deliminter log was a warning, not an error; webdoc can work without the delimiter too.

obiot · 2022-06-06T01:05:37Z

oh ok, it's just a warning actually, I thought the parser was then "ignoring" those lines because of the missing "-". Got it !

obiot · 2022-06-06T01:12:31Z

wow, already much more less scary now to see the parsing log 👍

ShukantPal · 2022-06-07T02:23:03Z

Published 1.6.1 to fix all of these issues. https://github.com/webdoc-labs/webdoc/releases/tag/v1.6.1

There's another problem in this codebase. It uses @function to describe class methods. webdoc makes a distinction between functions and methods; methods are members of a class whereas functions are considered "independent".

I think we could just get rid of the verbose @function tags in most of the codebase since webdoc infers it's a method by default.

ShukantPal · 2022-06-08T02:50:14Z

Yeah def retheming is the way to go IMO.

thanks again for all your support, really appreciate it ! be sure I'll do a big shout out for Webdoc once its all completed :):):)

Much appreciated! Happy to see webdoc getting used!

obiot · 2022-06-08T03:59:26Z

2. Add stylesheets: https://github.com/webdoc-labs/pixijs/blob/df56af7614d7e1d68b588dd0f2ceebf8d7e74021/webdoc.conf.json#L56. If you need help for anything specific here, I can help you once you've setup the CSS files in this repo.

oh well If I need to add specific files in the melonJS repo for the docs, I'd rather then copy the template in his own repo and modify it from there to be honest. I've been trying to "unclutter" things by removing as much as possible and I have no "place" to put those stylesheets

ShukantPal · 2022-06-08T04:01:50Z

@obiot In this case, you're not actually copying webdoc's code - these are your theme's stylesheets. I think you'd need at most 1 or 2 CSS files.

You could make a separate repo with the stylesheets and use git submodules to import them in this repo too. Or just publish the CSS files to npm and then pull them from inside node_modules, e.g. ./node_modules/@melon/webdoc-template/melon-theme.css

obiot · 2022-06-08T05:37:36Z

@ShukantPal sorry about all the questions, but one more : what about all the images I'm using with the current jsdoc template: https://github.com/melonjs/jsdoc-template/tree/main/static/images

ShukantPal · 2022-06-08T13:53:04Z

@obiot Ideally, they should be put in a CDN and you can use the absolute URL. webdoc will eventually support in-repo assets but not atm.

ShukantPal · 2022-06-08T13:53:41Z

I think there's a way to import static assets in webdoc actually. I'll let you know after work today

ShukantPal · 2022-06-09T03:19:36Z

Nevermind, I'm adding support for copying assets over in the upcoming release.

ShukantPal · 2022-06-09T04:04:56Z

@obiot Can you upgrade to webdoc 1.6.2 and set template.assets to the directory static in the jsdoc-template repo? This should make all images work in your documentation.

{
  "template": {
    "assets": ["./path/to/static"]
  }
}

obiot · 2022-06-09T04:08:51Z

wow so fast ! will it work if I add both the stylesheets and static images to a @melonjs/webdoc-theme repository that I would publish to npm so that i can do :

 "template": {
    "assets": ["./node_modules/@melon/webdoc-theme/static"]
    "stylesheets": [
      "./node_modules/@melon/webdoc-theme/stylesheets/index.css",
      "./node_modules/@melon/webdoc-theme/stylesheets/header.css",
      "./node_modules/@melon/webdoc-theme/stylesheets/md.css"
    ],

ShukantPal · 2022-06-09T04:09:27Z

@obiot Yes.

obiot · 2022-06-09T04:11:37Z

awesome, will try all that this afternoon, create the repo and populate it, thanks again for your super fast support !

funny to see how 2 somehow similar projects like pixi and melonjs (I mean 2 javacript or typescript framework) have some many different use cases when it comes to documentation ! this will for sure (hopefully) benefit all future framework that will migrate to webdoc too !

ShukantPal · 2022-06-09T04:18:17Z

@obiot I was browsing through the MelonJS docs locally and saw that Light2d isn't documented in the current website (but webdoc is picking it up):

melonJS/src/renderable/light2d.js

Line 22 in ae6d3a3

/**

Bug in JSDoc?

obiot · 2022-06-09T04:24:13Z

No I just did not publish the latest doc actually ☺️ and since its more of an experimental feature anyway for now i’d figure it can wait for webdoc to be ready.

by the way do you know how to automatically publish to gh-pages? I tried to do it for the doc in the past but never succeeded

ShukantPal · 2022-06-09T04:28:36Z

I would recommend you setup a GitHub workflow with a Deploy to GitHub pages.

obiot · 2022-06-09T07:22:03Z

@ShukantPal I just updated to the latest 1.6.2 version and modified the conf file as follow :

    "template": {
        "applicationName": "melonJS",
        "repository": "@webdoc/default-template",
        "outputSourceFiles": false,
        "readme": "./README.md",
        "repository": "https://github.com/melonjs/melonJS/",
        "assets": ["./node_modules/@melonjs/jsdoc-template/static"]
    }

however the path to the assets is not correct, as you can see below it properly fetch the html, but when it comes to the images the base docs root folder is not taken in account : /assets/images/convex_polygon.png should be /docs/ /assets/images/convex_polygon.png

Serving HTTP on :: port 8000 (http://[::]:8000/) ...
::1 - - [09/Jun/2022 15:18:21] "GET /docs/melonjs/Polygon.html HTTP/1.1" 200 -
::1 - - [09/Jun/2022 15:18:21] code 404, message File not found
::1 - - [09/Jun/2022 15:18:21] "GET /assets/images/convex_polygon.png HTTP/1.1" 404 -
::1 - - [09/Jun/2022 15:18:21] "GET /docs/styles/index.css HTTP/1.1" 200 -
::1 - - [09/Jun/2022 15:18:21] "GET /docs/icons/link.svg HTTP/1.1" 200 -
::1 - - [09/Jun/2022 15:18:21] "GET /docs/icons/chevron-up.svg HTTP/1.1" 200 -
::1 - - [09/Jun/2022 15:18:21] "GET /docs/icons/chevron-down.svg HTTP/1.1" 200 -
::1 - - [09/Jun/2022 15:18:21] "GET /docs/scripts/default-template.js HTTP/1.1" 200 -
::1 - - [09/Jun/2022 15:18:21] code 404, message File not found
::1 - - [09/Jun/2022 15:18:21] "GET /assets/images/convex_polygon.png HTTP/1.1" 404 -
::1 - - [09/Jun/2022 15:18:22] "GET /docs/explorer/reference.json HTTP/1.1" 200 -

obiot · 2022-06-09T08:09:54Z

latest update :

new repository for the melonJS theme : https://github.com/melonjs/webdoc-theme
conf file updated accordingly: https://github.com/melonjs/melonJS/blob/master/webdoc.conf.json#L14-L26

colors are not yet fully right (I'd like to have the banner in a dark gray color, and then use the melonJS green for main text and highlight; basically same as we have now more or less: http://melonjs.github.io/melonJS/docs/), and the image assets are not yet there (as per my last feedback), but we are almost there !

ShukantPal · 2022-06-09T13:46:22Z

I'll fix the image linking problem later today then!

ShukantPal · 2022-06-10T00:26:22Z

Looking at your theme - I didn't realize the PixiJS theme was that good 😂.

obiot · 2022-06-10T00:30:02Z

ahahahaha thanks 😂 I've been struggling yesterday to make the webdoc one looks like the former jsdoc really (and you see how (not) far I managed to do)

ShukantPal · 2022-06-10T01:15:42Z

ahahahaha thanks 😂 I've been struggling yesterday to make the webdoc one looks like the former jsdoc really (and you see how (not) far I managed to do)

No worries. How does this look?

ShukantPal · 2022-06-10T01:18:15Z

Made a PR with the changes: melonjs/webdoc-theme#1

obiot · 2022-06-10T02:16:53Z

you are the best ! Looking at your changes in the css, I would have never figured it out :P but I suck at web/css design, thanks a bunch, really ! I think that's ready now for publishing now, can't see right what is still missing honestly. I'll review the doc carefully for anything missing and then will go ahead !

…asically done

obiot · 2022-06-12T03:40:38Z

Hi @ShukantPal,

I was trying to to put the final touch at the documentation before publishing, but I could not find how to add a footer in the template, is it something I missing, or is not possible in the current version (which is ok, just want to add something similar to jsdoc: copyright + generated by webdoc)

also I tried to Look at Algolia, create an account and everything, but I'm not sure what benefit it brings; I mean the filter/search field in the explorer is already good enough no ? and Algolia is not so simple to put in place.

I created an account, got my key and all, but when I tried to update the record and upload the json manifest file (which I assume is the one to use) I got the below error :
Upload error: Record at the position 0 objectID=97ef94bd024c5_dashboard_generated_id is too big size=1767006/100000 bytes. Please have a look at https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/in-depth/index-and-records-size-and-usage-limitations/#record-size-limits

ShukantPal · 2022-06-12T21:57:42Z

Hi @obiot, I pushed a PR to upgrade your webdoc installation to 1.6.5; that version lets you configure the footer without having to re-add “Powered by webdoc!” You can set the “template.alias.footer” property to a HTML fragment file (*.tmpl). You would basically be overriding this template file: https://github.com/webdoc-labs/webdoc/blob/master/packages/webdoc-default-template/tmpl/components/footer/index.tmpl In regards to Algolia, 1. I think you have to deploy your site first since Algolia will crawl through it. 2. You also have to set the “template.siteDomain” config in webdoc.conf.json to “http://melonjs.github.io<http://melonjs.github.io/>”. That will make webdoc generate a sitemap. Algolia uses the sitemap to find each page. 3. Make sure you’re using the DocSearch (legacy) Docker image: https://docsearch.algolia.com/docs/legacy/run-your-own. Then your Algolia command should look something like: [cid:68DF5987-B34A-46A7-9D26-775027306E99] If you invite me to your Algolia account, I might be able to give more help. The benefit of Algolia is that it is full-text search so people can search by keywords in class descriptions and members too. On Jun 11, 2022, at 11:40 PM, Olivier Biot ***@***.******@***.***>> wrote: Hi @ShukantPal<https://github.com/ShukantPal>, I was trying to to put the final touch at the documentation before publishing, but I could not find how to add a footer in the template, is it something I missing, or is not possible in the current version (which is ok, just want to add something similar to jsdoc: copyright + generated by webdoc) also I tried to Look at Algolia, create an account and everything, but I'm not sure what benefit it brings; I mean the filter/search field in the explorer is already good enough no ? and Algolia is not so simple to put in place. I created an account, got my key and all, but when I tried to update the record and upload the json manifest file (which I assume is the one to use) I got the below error : Upload error: Record at the position 0 objectID=97ef94bd024c5_dashboard_generated_id is too big size=1767006/100000 bytes. Please have a look at https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/in-depth/index-and-records-size-and-usage-limitations/#record-size-limits — Reply to this email directly, view it on GitHub<#1089 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AFLJDBZ5FQPGT62CVSOSQX3VOVL4DANCNFSM5REUUUMA>. You are receiving this because you were mentioned.Message ID: ***@***.***>

obiot · 2022-06-12T23:54:40Z

fantastic, thanks !

for Algolia I will wait next release then, plublish this version first, and indeed then let it crawl the online doc.

thanks again :)

obiot · 2022-06-12T23:55:25Z

I'm gonna close this ticket too, we are done here I believe :) we can still come back here for discussion of course.

ShukantPal changed the title ~~Replace JSDoc as it not maintained~~ Replace JSDoc as it is not maintained and is legacy software Mar 19, 2022

obiot added a commit that referenced this issue Jun 1, 2022

[#1089] initial webdoc support

6174558

doc generation currently failing !

obiot referenced this issue Jun 6, 2022

update to latest version of webdoc

a89ca95

obiot added a commit that referenced this issue Jun 6, 2022

[#1089] webdoc: quiet warning(s) on missing "-" delimiter

bd643c2

ShukantPal mentioned this issue Jun 9, 2022

Feature: Add support for copying assets and replace img src with the proper path in @webdoc/default-template webdoc-labs/webdoc#170

Merged

obiot added a commit that referenced this issue Jun 10, 2022

[#1089] officially remove JSDoc now that the migration to Webdoc is b…

56092de

…asically done

obiot added a commit that referenced this issue Jun 12, 2022

[#1089] forgot to remove that one too

70f35bd

obiot closed this as completed Jun 12, 2022

Replace JSDoc as it is not maintained and is legacy software #1089

Replace JSDoc as it is not maintained and is legacy software #1089

Comments

ShukantPal commented Mar 19, 2022

obiot commented Mar 21, 2022

ShukantPal commented Mar 21, 2022

obiot commented Jun 1, 2022 • edited Loading

ShukantPal commented Jun 1, 2022 • edited Loading

obiot commented Jun 1, 2022

obiot commented Jun 1, 2022 • edited Loading

obiot commented Jun 1, 2022

obiot commented Jun 1, 2022

obiot commented Jun 5, 2022

ShukantPal commented Jun 5, 2022

obiot commented Jun 6, 2022

ShukantPal commented Jun 6, 2022 • edited Loading

obiot commented Jun 6, 2022

obiot commented Jun 6, 2022

ShukantPal commented Jun 6, 2022 • edited Loading

obiot commented Jun 6, 2022

obiot commented Jun 6, 2022

ShukantPal commented Jun 7, 2022

ShukantPal commented Jun 8, 2022

obiot commented Jun 8, 2022

ShukantPal commented Jun 8, 2022

obiot commented Jun 8, 2022

ShukantPal commented Jun 8, 2022

ShukantPal commented Jun 8, 2022

ShukantPal commented Jun 9, 2022

ShukantPal commented Jun 9, 2022

obiot commented Jun 9, 2022

ShukantPal commented Jun 9, 2022

obiot commented Jun 9, 2022 • edited Loading

ShukantPal commented Jun 9, 2022 • edited Loading

obiot commented Jun 9, 2022

ShukantPal commented Jun 9, 2022

obiot commented Jun 9, 2022 • edited Loading

obiot commented Jun 9, 2022 • edited Loading

ShukantPal commented Jun 9, 2022

ShukantPal commented Jun 10, 2022 • edited Loading

obiot commented Jun 10, 2022 • edited Loading

ShukantPal commented Jun 10, 2022

ShukantPal commented Jun 10, 2022

obiot commented Jun 10, 2022

obiot commented Jun 12, 2022

ShukantPal commented Jun 12, 2022 via email

obiot commented Jun 12, 2022

obiot commented Jun 12, 2022

obiot commented Jun 1, 2022 •

edited

Loading

ShukantPal commented Jun 1, 2022 •

edited

Loading

obiot commented Jun 1, 2022 •

edited

Loading

ShukantPal commented Jun 6, 2022 •

edited

Loading

ShukantPal commented Jun 6, 2022 •

edited

Loading

obiot commented Jun 9, 2022 •

edited

Loading

ShukantPal commented Jun 9, 2022 •

edited

Loading

obiot commented Jun 9, 2022 •

edited

Loading

obiot commented Jun 9, 2022 •

edited

Loading

ShukantPal commented Jun 10, 2022 •

edited

Loading

obiot commented Jun 10, 2022 •

edited

Loading