Add docstrings for core

[chris48s]

:clipboard: Description

Some of the shields internal API is documented with JSDoc strings. For example, https://github.com/badges/shields/blob/master/core/base-service/base-json.js is annotated with comments which can then be compiled into API documentation https://contributing.shields.io/module-core_base-service_base-json-BaseJsonService.html

Ideally it would be great to have full documentation for the core API and service helpers. At this stage, I'm not too concerned about trying do document the individual service implementations - they basically all follow the same pattern so documenting the core framework is really the priority.

Task: Find a class or function under https://github.com/badges/shields/tree/master/core or the root of https://github.com/badges/shields/tree/master/services (not subdirs) without a DocString and add documentation describing the:

• purpose/behaviour
• parameter types/descriptions
• return type

Use npm run build-docs to check the compiled docs and see https://jsdoc.app/ for help with JSDoc syntax.

[pr7prashant]

@chris48s I would like to work on this issue if it's still required. I'm new here and this looks like a good issue to get to know about the project.

[chris48s]

Thanks. Yes there are still plenty of functions missing docs, particularly for commonly used helpers in the root of /services. If you want to start picking some up that would be cool. My advice would be to start small and submit one or two PRs adding docstrings for a few functions or classes. Don't try to boil the ocean all at once :)

[ZPain8464]

@chris48s if there is still a need here, I'd like to contribute. I should also mention that I'm new here, but am eager to help out.

[pr7prashant]

@chris48s if there is still a need here, I'd like to contribute. I should also mention that I'm new here, but am eager to help out.

@ZPain8464 Hi, yes there are still plenty of core modules left. I do it one file at a time when I get some free time. You can also chip in :)

[calebcartwright]

@chris48s if there is still a need here, I'd like to contribute. I should also mention that I'm new here, but am eager to help out.

That's fabulous to hear! @pr7prashant has done great work making progress on these, and as noted above there's indeed still some left to do. Sure we could find some other issues that might be good candidates to help getting used to the Shields codebase too.

[pr7prashant]

Small update: #9495 should conclude documentation for base services excluding the sub directories.

[chris48s]

This is awesome. That really covers the functions that new contributors are most likely to interact with and need help with. Really appreciate your work on this.