JS documentation / documentation coverage

[audreyfeldroy]

DeepSource says we have 5% documentation coverage. I'm actually not sure where that 5% even comes from, to be honest.

For this issue, help us set up documentation for our JS code in a way that documentation coverage numbers can be checked by DeepSource.

You don't have to actually write all the documentation...you or others can pitch in later with PRs for it.

This may involve reading up on best practices for modern JS documentation. What's the best tool for this currently? Is it ESDoc or something else?

[endreymarcell]

Hey there! According to DeepSource, this metric shows "the number of scopes that have some sort of documentation added, versus the number of scopes (classes, functions, structs, modules) that exist in a given codebase." In other words, you can achieve 100% on this scale if you add a comment to every single thing you add to the codebase. That is a very impractical thing to do. I'm not familiar with DeepSource per se but in my personal opinion, this metric is misleading and should not be in their report. It is a very bad use of anyone's time and energy to try to strive for high documentation coverage just for the sake of high documentation coverage except in some very specific cases, like public APIs.

The prevailing sentiment among clean code enthusiasts is that in most cases, comments can be avoided by writing clean and expressive code, and it is a better idea to do so. There are exceptions, but those are exceptions, not the rule. Source: the famous Clean Code by Robert C. Martin (the book is a great read, but you can also watch him give present it on YouTube, here's the Lesson 2 which addresses comments), any number of blog posts, plus personal experience.

[audreyfeldroy]

Hi @endreymarcell, thanks for looking into how DeepSource calculates documentation coverage, and for sharing your perspective, it really helps me and everyone understand this better.

Clean Code is an excellent book. I'm watching the Lesson 2 video with @pydanny and it's good! Thanks for the recommendation. And I definitely agree with not adding comments to every single thing, haha. Let me clarify what I had in mind...

For this issue I think a good to-do checklist is:

• [ ] Create docstrings for at least 2 items in Card.js, e.g. the top of the main file itself and the Card function
• [ ] Set up ESDoc to generate documentation in HTML format from those docstrings
• [ ] Configure ReadTheDocs.org to auto-build the HTML docs

[endreymarcell]

I suggest we stop and think about what is the goal here. Public documentation (as in generated HTML pages and readthedocs.org) is generally used for projects which are to be consumed by other developers such as packages, libraries, frameworks. It is expected for things like react, next.js, eslint, or prettier. These all provide some kind of interface/API towards other developers that is documented. However, you're building a webpage here, so you're not really exposing any code that would require documentation. The only use-case I see is that you'd like other to be able to contribute to your code so you want to add some comments here and there to make the code easy to understand and extend. Fair enough - but this doesn't warrant a readthedocs page or anything of the sort.

Sorry, I'm in no position to tell you how to run your project. I was just browsing through some "help wanted" issues on GitHub, stumbled upon yours, and stopped by to give my two cents. :) Hopefully I'll soon find the time to actually contribute too, not just comment.

[audreyfeldroy]

I appreciate the feedback @endreymarcell! Thanks for taking the time to comment again and share your thoughts further.

Let's hold off on this issue until we have the exact use case for the documentation figured out.

[audreyfeldroy]

I think the code is starting to get complex enough that we need docs on ReadTheDocs. Contributors are starting to get overwhelmed and need additional guidance, and CONTRIBUTING.md isn't enough in my experience running big open source projects.

If anyone wants to help with the documentation effort, come discuss it in https://app.element.io/#/room/#mhf:matrix.org 😃

[audreyfeldroy]

I've set up docs with GitBook at https://audreyfeldroy.gitbook.io/help-a-family-manual/

• The Markdown files used to generate that are at https://github.com/margaritahumanitarian/helpafamily-manual

GitBook likes to have full control over file locations...I was hoping to set it up with our existing docs/ folder, but it moved around the images and broke the main site.

I'm open to other documentation tools but I'm starting to like GitBook a lot, as it makes it very fast for me to update docs.

Not sure if GitBook has ESDoc or similar integration. Anyone want to explore that? My guess is we'll need a separate API documentation site.

About API use cases, I've documented two of my ideas using a documentation-driven approach at https://audreyfeldroy.gitbook.io/help-a-family-manual/info-for-api-users

[IAmRiteshKoushik]

Hey, I just came across this project and noticed that you require help with JS Documentation. Is the issue still open ? If yes, I can try contributing to ti. By the way, I am getting a 404 on the https://audreyfeldroy.gitbook.io/help-a-family-manual/info-for-api-users