API documentation

[jsumners]

It doesn't exist. Having to dig through source code that doesn't contain a single comment, much less some documentation headers, to try and figure out what would be necessary to write a plugin is a major turn off. Especially when the promoted "hook" interface's list of hooks simply links to a "it's around here" section of the source code. Great, that's where the source code defines the hook. What does it do? How do we use it? Another example is middleware/cls.js and the socket function. There is absolutely no instruction on how to use it.

Documentation isn't fun to write. But it's a necessity when you are building a platform upon which you expect others to build.

[pitaj]

Possibly use JSDoc or ESDoc or Typescript for automatic documentation generation.

[jsumners]

Exactly. Even if they source files are never run through jsdoc, the code should have the doc blocks present.

[akhoury]

@jsumners I agree, there is a lack of documentation, you've probably you seen this
https://docs.nodebb.org/en/latest/plugins/create.html and this https://github.com/NodeBB/NodeBB/wiki/Hooks - and in a perfect world, yes that sucks, but in reality when it comes to writing plugins, there are hundreds of examples, and as for the hooks, here's what each type of hook, action, filter and static actually mean, and anything after the colon : is self descriptive IMO - i.e action:post.save, at least for the hooks.

I also agree, there isn't many comments in the code, but to be honest, it's also mostly self explanatory as well, comments are only useful when your code is doing something weird, at least that's my opinion, other then that, meaningful variable names are usually enough - however, i don't think the lack of logic comments is the problem, i think if each "model-or-class" (i.e. user, post etc. ) had a generated list of functions with signatures and short descriptions, that would be great to base our plugins off of (here JSDoc would be an amazing start if the core-teams agrees)

Also, since you asked about CLS
https://docs.nodebb.org/en/latest/plugins/create.html#getting-a-reference-to-each-request-from-within-any-plugin-hook

To be clear, I am not suggesting that you close this ticket nor that documentation isn't something necessary, I am just giving you a reasonable alternative till the documentation gets written.

Keep in mind that this is an open source and free project, and as you mentioned, docs aren't easy to write. Also feel free to help, we all try to.

[jsumners]

@akhoury I am firmly not in the "code is enough" camp. It takes longer to read through code that isn't your own than it does to read through proper API documentation, i.e. the output of jsdoc.

Yes, the hook names are clear. But their signatures are not. What values do they accept? What do they really do with them? It's a mystery unless you sit down and study the code when you'd rather be writing your own. The same goes for all of the non-hook API.

I do not have time to sit down and read through NodeBB's source code, determine whether or not I understand what it does and how it fits in with the rest of the code, and then write documentation for it. I have my own long list of projects to work on. Including one that should be a simple plugin/widget for a NodeBB instance I have setup. But it's been so much of a chore tracking down those "hundreds of examples" and wading through NodeBB's source that I haven't gotten past rendering some HTML in a sidebar.

[pitaj]

I don't think anyone is suggesting that "code is enough." Obviously, docs are necessary, not only for API declaration, but for examples, installation, etc.

[julianlam]

Thank you everybody for your thoughts. I'm in the midst of moving from one house to another, but I've been keeping tabs on this discussion so I wanted to chime in in between trips.

@jsumners Please know that we do consider our minimal documentation as lacking. There are many other priorities for the NodeBB team, including maintenance of the core code, introduction of new features, security fixes, changes and updates to plugin support, etc. (not to mention the bunch of stuff we do with NodeBB to actually put food on our tables 😄 )

Documentation is important, and it is unfortunate that it has been on a lower priority, though it is definitely something we do want to address sooner or later, as it is directly beneficial to third-party developers such as yourselves.

At this point, if the current documentation is lacking, I would recommend posting your exact troubles to the community support forum, and there will be members there (including us, from time to time!) who will contribute and resolve your issues.

If you're like me, you'd prefer to read API documentation and resolve the issue yourself, and trust me, I know how annoying it is when it isn't present.

Your thoughts have been heard 😄

[jsumners]

Food > text. Agreed.

In regard to the forums suggestion. I simply don't want to deal with yet another account. It looks like you guys have a Gitter channel, so maybe I'll drop by there for some questions. But, as you said, I'd rather just be able to read the docs.

[Radiergummi]

I would volunteer to at least add Docblocks to the core, if you guys are
interested (since I am working on an automated documentation generator for
Node projects in my company that needs testing anyhow). I used large
portions of the NodeBB core in my own projects, so I could write sensible
function descriptions for most core code, too.

James Sumners notifications@github.com schrieb am Do., 16. Juni 2016 um
16:41 Uhr:

Food > text. Agreed.

In regard to the forums suggestion. I simply don't want to deal with yet
another account. It looks like you guys have a Gitter channel, so maybe
I'll drop by there for some questions. But, as you said, I'd rather just be
able to read the docs.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#4750 (comment), or mute
the thread
https://github.com/notifications/unsubscribe/AF1QZaAAamPNu8trpFnIpAS7AVoUy5glks5qMWClgaJpZM4IzoJU
.

[yariplus]

Use JSDoc format, push to the github wiki, using something like this, add it to travis so it updates on every push.

All the developer stuff should be on the wiki imo.

[exomarty]

Code is only self explanatory to whoever write it. Thinking that is just wrong.
The lack of documentation on nodebb made developers and amateur codes run away and nowadays only a few left.

[psychobunny]

There is absolutely no argument against the fact that we need more docs. I even wrote a bot that scoures the code to automatically update hook docs. More of that will come. This is closable because it's something that's already on our roadmap.

I do apologise though. For the time being, our community is the best bet for asking for help.

@Radiergummi any help is greatly appreciated:)

[jsumners]

I don't see how it's closeable when it hasn't been fixed. The "bug" is still present regardless of future ambition.

[pitaj]

@psychobunny This shouldn't be closed unless you want to re-open a new issue for tracking progress on documentation.

[chriserwin]

@psychobunny Any update on this? We're evaluation forum software right now and the lack of API documentation is a bit of a show stopper for us.

[julianlam]

@chriserwin yes -- the Write API itself is fully documented, but the Read API is not. We have a project ongoing to bring auto-generated documentation to the frontend via OpenAPI.

We don't have details to share as of yet, but we're hoping to have something to show soon!