Maintenance of the JSDoc project going forward

[iansan5653]

This project affects pretty much every production JavaScript developer and is hugely important for the community, yet there have been no commits since September 3rd of last year (2017). JavaScript is a continuously changing language and therefore JSDoc needs to be continuously updated and maintained to meet the needs of the community (as evidenced by the far more recent issues posted). Are there any plans to maintain this project going forward? If @hegemonic (the only recent contributor) no longer has time to maintain this repo, we should come up with a plan for the future.

I really appreciate the huge impact that JSDoc has had on my development, and I don't want to see it die. I think JSDoc is honestly one of the best things to happen to JavaScript.

[iansan5653]

Note this also applies to jsdoc3/jsdoc3.github.com.

[valsaven]

Agreed.
Ping @hegemonic @jannon @micmath @tschaub

[tschaub]

I don't have publish rights to the npm package and have certainly not been an active contributor.

If I were to help take over maintenance of the library, I would work to reduce its scope (removing support for multiple flavors of type syntax, removing duplicate/overlapping tags, simplifying the template/plugin system) in hopes of making it easier to maintain. I'm pretty sure this would be met by anger from existing users (who likely want it to do more things instead of doing fewer things better).

[lll000111]

I cannot even get a network graph from Github, which would show me who has a fork with what later commits or patches applied.

Does anybody know which forks have at least a few useful patches applied? I'm almost satisfied even with the old JSDoc3, but there are some oddities while parsing perfectly normal looking stuff that would probably easily be taken care of by one of the many already existing patches/PRs.

The worst part IMHO is that there is no search for a new maintainer. I was not too long ago left as an (heavily underpowered) co-maintainer of a popular repo where the actual maintainer just disappeared, did not even react to personal emails, no Github activity at all either. You know what I did? I changed the README to say in big bold letters what the situation was and that I was looking for new maintainers. I did not have sufficient Github rights on the repo, but what I did was change the README to point to the forked repo of the new maintainers. Here, there is nothing, total silence. If you cannot maintain it, just give it to somebody else.

I also tried esdoc, documentation.js and a few others, usually they don't even produce output because they too have issues, and maintenance is an issue for those packages too.

Given the difficulties of doing laborious maintenance for free, which everybody eventually tires of, there should be more flexibility to hand the project over. Given the huge amounts of forks of JSDoc3 this should be possible.

What might also work, as a workaround, is to list a few notable forks on the frontpage (README.md). At this point of standstill a "project hack mode" (meaning the things around the code that I mentioned, like the "README hacks") is perfectly okay I think. If you ask (at the top of the README) I'm sure they will come. The project I "gave away" (by README-pointer) had a lot less users and forks and is doing fine now under new ownership.

By the way, looking at the many many issues coming from people who think any issue they have with anything "JSCode" in the widest sense, like VSCode not displaying something correctly, is something that belongs here — maybe a new project fork should be renamed to indicate that this here is a tool to create offline API doc files, and not the "everything-JSDoc" repo :-) I certainly understand the confusion, originally it was okay, but now the name is a bit "too central" I think, now that JSDoc comments are in wide-spread use for many other things than creating documentation files, especially what IDEs like VSCode use it for. A lot of people expect some kind of type system (for the IDE, for coding support, for type lookups and quick documentation popups) plus all the infrastructure for it, judging by some of the issues I read.

[iansan5653]

@lll000111 I agree that the VSCode issues should be ported to that repo, but this is (as far as I know; I could be wrong) the repo that decides the standard (not just the doc generation) so, say, if a new feature gets added or JSDoc4 released, that would come from here. Maybe there should be a project just for administrating the standard going forward.

[lll000111]

@iansan5653 I don't understand your point, how it relates to anything I wrote. There is no "standard" to begin with, various people support various tags, a colorful mix from different sources and creating their own. Even the JSDoc3 release also supports closure compiler stuff. Also, this package is unmaintained. I doubt the original maintainer will suddenly come back full swing. Usually people produce code when they themselves need something. When that's over it's over, given that you have to work (a lot!) for free to maintain such a package.

Maybe there should be a project just for administrating the standard going forward.

As I said, there is no standard. Every tool chooses what they support, and while http://usejsdoc.org/ is a place many like to link to what tags which tool supports how is variable and highly depends on whatever the maintainer needs. There is much more confusion and variety ahead, just look at some of the feature requests. Just like JS programming style can vary extremely widely — I guess it's great that the language is so flexible — so do the needs of people who document their APIs. As the pirate said: "It's more like a guide".

[hegemonic]

I'm working on JSDoc again, so I'm closing this issue.