Add Typings using JsDoc

[noahweasley]

Since migrating to typescript is not an option, in the future, typings would be added to provided intellisense while using Node User Settings

[SujalChoudhari]

I wan't to help on this project, can you describe it.

• what exactly you want to document
• what should be the format of it
• what to skip/ give more importance on it
• basic conventions to follow

[noahweasley]

Thank you for wanting to contribute.

For now, I am trying to improve the project, there are a lot of things to be done. But I also want to provide typing, as in providing Typescript IntelliSense features but without using Typescript and having to re-write the project completely in Typescript.

If you could help generate the typings using JsDocs and JsDocs comments that would be very much appreciated.

Visit the contributing.md file to know about how to contribute

Please note: The tests always fail because of how the project was structured which I am also trying to fix, but that will be done later

[SujalChoudhari]

If I get it right? You want me to write JSDoc Comments for this Project. I assume it is just the ./src directory. Are you willing to convert it into a static docs website?

Edit: I found out that the ./src directory already contains JsDoc comments.

[noahweasley]

Do you use Typescript? If yes, then you know the significant difference between JS and Ts, the Intellisense and Auto-completion it brings to the IDE, unfortunately, Ts isn't used in this project, and JsDocs was used, but you could get that TYPING, which TS provides using JsDoc if you don't still know what it means check this website out How to get type-checking and generate TypeScript Typing declaration (types.d.ts) from JSDoc annotations. And No, the project does not require to generate a website

[SujalChoudhari]

Check this file, is this what you need? Forked Changes

The thing is, it shows,

/**
 * Initialize the preference API with configuration options.
 */
declare namespace __exports {
    /**

maybe you want something else instead of __exports?

[noahweasley]

No, don't change or rename anything, leave them the way they are. Just add the typing. Please also move the typedefs out of the src folder into a types.js file, all typedefs should go there and referenced in the src folder correctly.

Ensure that you document these types appropriately with JSDoc comments to provide clear documentation for users and enable better tooling support for editors with TypeScript-aware features.

/**
 * @typedef {Object} PreferenceConfig
 * @property {string} preferenceFileDir - The directory where preference files are stored.
 * @property {string} preferenceFileName - The name of the preference file.
 * @property {string} fileName - The name of the file.
 * @property {string} fileExt - The file extension.
 */

PreferenceConfig doesn't seem to provide documentation as to what it actually is.

Also, if you noticed, there are places where JSON was used as a type of parameter (which is vague), also generate typedefs (that is well documented), to provide info as to what this object would be.

[noahweasley]

Also moving forward, don't capitalize your commit messages, start with a lowercase (I will update the Contributing.md file soon with that info). This is the actual guideline:

1. Keep It Short and Descriptive:

   • Limit the first line of your commit message to 50 characters or less.
   • Write a concise but descriptive summary of the change. Imagine it as the subject of an email.

2. Use Proper Grammar and Punctuation:

   • Start the summary with a capital letter.
   • Use imperative mood (e.g., "Add feature," "Fix bug," "Update Documentation") for the first word of the summary.

3. Provide Additional Details in the Body:

   • After the summary, add a blank line and write a more detailed explanation of the change.
   • Describe why the change is necessary and what it accomplishes.
   • Include any relevant context, references, or issues.
   • Use bullet points or paragraphs for readability.

4. Reference Issue Numbers:

   • If your commit is related to a specific issue or task, reference it in the commit message.
   • Most platforms (e.g., GitHub, GitLab) automatically link issues when you use a keyword followed by the issue number (e.g., "Fixes #123").

5. Separate the Summary and Body:

   • Use a blank line to separate the summary from the body for better readability.

6. Use Present Tense:

   • Write commit messages in the present tense. Instead of "Fixed bug," use "Fix bug."

7. Be Consistent:

   • Maintain a consistent style and tone for your commit messages throughout the project.

Here's an example of a well-formatted Git commit message:

Add validation for user input

This commit adds input validation to the user registration form to prevent
SQL injection attacks and improve security. It validates user inputs
including username, email, and password against a set of rules defined
in the validation module.

Fixes #123

[noahweasley]

Also, note that the dev branch was what I was working on to create a new release, so I have created a new branch called Staging and opened a pull request against that staging branch (and not Master!). I will also restructure the guide on how to make a pull request later.