Improve validity and consistency of JSDoc comments #125
Labels
housekeeping
Refactoring, tidying up or other work which supports the project
Comments
Cruikshanks
added
the
housekeeping
Cruikshanks
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Aug 12, 2024
DEFRA/water-abstraction-team#125 Using [JSDoc comments](https://jsdoc.app/) to document our code has become our convention. We add `@module` declarations by default, detail our public methods, including params and returns, and have even added markdown sections in some places. Recently we went on a deep dive of **JSDoc** to generate documentation from what we've added so far. The good news is that it confirmed that we've got a lot of stuff right! But there are some things we've got wrong, plus some errors that make comments invalid. This change adds **JSDoc** as a dev-dependency to the project. We can then use it to generate documentation on request. We configure it to error when it encounters documentation it cannot parse, which serves as a means to validate that what we've done is 'error free'. What we've added may parse without error, but still may not be correct. Being able to generate the documentation will allow us to view how what we've added is presented and makes corrections as and when needed. We finish this change by correcting the errors and misunderstandings we have now.
Cruikshanks
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Aug 13, 2024
DEFRA/water-abstraction-team#125 Using [JSDoc comments](https://jsdoc.app/) to document our code has become our convention. We add `@module` declarations by default, detail our public methods, including params and returns, and have even added markdown sections in some places. Recently, we went on a deep dive of **JSDoc** to generate documentation based on what we've added so far. The good news is that it confirmed that we've got a lot of stuff right! But there are some things we need to correct, plus some errors that make comments invalid. This change adds **JSDoc** as a dev dependency to the project. We can then use it to generate documentation on request. We then add it to our CI, where it will error when it encounters documentation it cannot parse, which serves as a means to validate that what we've done is 'error-free'. To ensure CI doesn't fail after this change, we correct our current errors. From now on, we'll catch any parsing errors. Hopefully, generating the documentation will also allow us to view how what we've added is presented. Having carried out this work, we know there are some issues to be fixed, but those are for another PR!
This was referenced Aug 20, 2024
Cruikshanks
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Aug 21, 2024
DEFRA/water-abstraction-team#125 We recently added a new [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc) plugin in [Lint JSDOC's](#1269) to take our work of helping new and existing devs follow our JSDoc conventions to the next level. For reference, we document we aim to document all our public functions. Forcing devs to write about why something exists is a handy way to try and slow them down and think about what they are doing! But we don't ask anyone to document private functions, for example, `function _determineStartDate()`. Basically, anything with a leading underscore. However, there are times where a comment is handy. We have to do some gnarly stuff on this service and some times we just can't make the code self documenting. 😢 At the moment, the plugin is penalising us for doing this. These comments don't include params and return statements because that was not the intent of the comment. So, this change is about getting the plugin to ignore private methods.
Cruikshanks
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Aug 21, 2024
DEFRA/water-abstraction-team#125 We recently added a new [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc) plugin in [Lint JSDOC's](#1269) to take our work of helping new and existing devs follow our JSDoc conventions to the next level. For reference, we aim to document all our public functions. Forcing devs to write about why something exists is a handy way to try and slow them down and think about what they are doing! But we don't ask anyone to document private functions, for example, `function _determineStartDate()` — basically, anything with a leading underscore. However, there are times when a comment is handy. We have to do some gnarly stuff on this service, and sometimes, we can't make the code self-documenting. 😢 At the moment, the plugin is penalising us for doing this. These comments don't include params and return statements because that was not the intent of the comment. So, this change is about getting the plugin to ignore private methods.
jonathangoulding
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Aug 23, 2024
DEFRA/water-abstraction-team#125 Previous work #1269 Building on from previous work of using eslint to handle out code conventions this change will use the auto fix feature of eslint and fix any errors relating to required public seeder descriptions.
jonathangoulding
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Aug 23, 2024
DEFRA/water-abstraction-team#125 Previous work #1269 Building on from previous work of using eslint to handle out code conventions this change will use the auto fix feature of eslint and fix any errors relating to required public seeder descriptions.
Jozzey
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Aug 29, 2024
DEFRA/water-abstraction-team#125 We use skinny controllers that don't do much more than call a service and return a view. We have therefore decided that it is not necessary to add JSDoc comments to our controllers. This PR will add an override to the linting rules so that JSDoc comments are not required for the controllers.
jonathangoulding
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Oct 29, 2024
* Fix JSDOC's lint seeder descriptions DEFRA/water-abstraction-team#125 Previous work #1269 Building on from previous work of using eslint to handle out code conventions this change will use the auto fix feature of eslint and fix any errors relating to required public seeder descriptions.
Cruikshanks
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Nov 15, 2024
DEFRA/water-abstraction-team#125 In [Lint JSDOC's](#1269) we added linting of our JSDoc comments. If we are going to do it, we might as well do it properly and consistently! There were quite a few, so since then we have cleaned up certain areas of the codebase, whilst configuring the linter to only warn of us of issues. With this final change we deal with the remaining issues so we can switch the linter to error when it encounters an issue.
Cruikshanks
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Nov 19, 2024
DEFRA/water-abstraction-team#125 In [Lint JSDOC's](#1269) we added linting of our JSDoc comments. If we are going to do it, we might as well do it properly and consistently! There were quite a few, so since then we have cleaned up certain areas of the codebase, whilst configuring the linter to only warn of us of issues. With this final change we deal with the remaining issues so we can switch the linter to error when it encounters an issue.
Cruikshanks
added a commit
to DEFRA/water-abstraction-system
that referenced
this issue
Nov 19, 2024
DEFRA/water-abstraction-team#125 In [Lint JSDOC's](#1269), we added linting of our JSDoc comments. If we are going to do it, we should do it correctly and consistently! There were quite a few, so since then, we have cleaned up certain areas of the codebase while configuring the linter to only warn us of issues. With this final change, we deal with the remaining issues so we can switch the linter to error when it encounters an issue.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Using JSDoc comments to document our code has become our convention.
We add
@moduledeclarations by default, detail our public methods, including params and returns, and have even added markdown sections in some places.A recent change to water-abstraction-system pushed forward the idea of using @typedef tags to define types.
I ( @Cruikshanks ) pushed the idea back for reasons documented in the PR, believing that the same details could be detailed using the existing @param or @returns.
This was attempted, but something didn't appear to be correct. Rather than provide more faulty advice, I've taken a deep dive into JSDoc.
This involved using JSDoc to generate documentation from what we've added so far. The good news is that it confirmed that we've got a lot of stuff right! But there are some things we've got wrong, plus some errors that make comments invalid.
This issue covers ideas and changes linked to improving the validity and consistency of the JSDoc documentation we add to water-abstraction-system.
Ideas/Plans
The text was updated successfully, but these errors were encountered: