I’m debating how to do documentation in my own project. I was thinking to have docs in inline comments in my code, but then having docs in different spoken languages could get out of hand.
Three.js has docs in English and Chinese. Are the Three.js Chinese docs up to date with English docs? Is it worth having multiple documentation languages? If there are changes to the docs, does one have to wait for the other languages to be updated before releasing?
Maybe I should roll with the fact that people who learn to code in mainstream programming languages also learn English (regardless if that’s fair or not, which is another topic), and just not worry about it for now?
What’s your take on code documentation?
Mostly. Some mindful Chinese contributors update the docs from time to time to the latest state.
The project is not doing that. Of course it’s ideal if all docs are in sync but I would not expect this from Open-Source projects with no real organization.
I personally favor inline documentation in English. The additional (type) information make it easier to read and understand the code, especially in JavaScript. Having code and documentation together makes it also easier to keep everything in sync.
1 Like
I like inline documentation too. The problem I have now is that I’ve migrated my code from JS to TypeScript, and now the jsdoc generator I was using doesn’t work. I tried TypeDoc, but the HTML output leaves much to be desired, plus it takes full control of documentation, rather than letting me document the library how I want to by hand; I mean, it assumes I want to document every type, when really I don’t, and other issues like with mixin classes.
Unless I find a good solution for inline TS documentation (gotta pass on TypeDoc), then I may just have to write separate markdown files for the time being.