Enhance Documentation Using JSDoc/TsDoc Standards

[h0ngcha0]

The SDK codebase would benefit from consistent, high-quality documentation to improve maintainability, ease of use, and on-boarding for new developers. To achieve this, we propose adopting JSDoc and/or TSDoc standards throughout the project. This will provide a standardized way to document functions, classes, parameters, return types, and modules, making it easier to generate comprehensive, up-to-date documentation.

Please start with the web3 package.

[alanJames00]

I would like to work on this.
Is there any specific requirements on tooling ?
I'm currently assuming the following:

1. Go with TSDoc since the codebase is already using TypeScript
2. typedoc and ts-doc as devDependencies.
3. Default linter config

[polarker]

Hey @alanJames00, those requirements are excellent!

I’d like to suggest an additional requirement to enhance developer usability:

• Developers should be able to easily navigate the web3 package using the generated documentation.

Here are a couple of points to consider:

1. Set up tools to generate HTML or Markdown documentation from JSDoc/TSDoc annotations for easy external reference.
2. Ensure that when the SDK is installed as a dependency, developers can navigate the documentation directly within their IDE by jumping to definitions.

[alanJames00]

Got it. I will start working on the web3 package mentioned in the Issue.

[Michaelkingsdev]

I can handle this issue. I will deliver in 72hrs when ODHack starts.

[Mystic-Nayy]

Hi @h0ngcha0 @ Can I work on this ?
I am a web3 developer/ Technical writer
I have experience in a lot of open source contributions especially in writing Documentation
Here are some of the merged docs I’ve written
Flex-NFT-Marketplace/Flex-Marketplace-Contract@fc28412
https://hackmd.io/@xZ4BOZ5TTTy1I0ZQHXFOkg/rkFBcGgAC
dragan2234/worldcoin-scroll-bridge#29,

I will Set up tools to generate HTML or Markdown documentation from JSDoc/TSDoc annotations for convenient external reference.
Make sure that when the SDK is installed as a dependency, developers may access the documentation straight from their IDE by jumping to definitions.

ETA- 24HRS

[alanJames00]

Due to some personal issues, I'm taking a break, The issue could be assigned to other contributors. Thank You.

[0xdevcollins]

@polarker can I work on this?

My Approach

Since TypeScript is currently used in the codebase, I will add typedoc and tsdoc as devDependencies and use TSDoc for documentation. I'll use the default linter configuration to guarantee consistent code and documentation quality. With the help of the documentation and setup tools, I will also make it simple for developers to use the web3 package and transform JSDoc/TSDoc annotations into HTML or Markdown for external reference. When the SDK is installed as a dependency, I'll also enable in-IDE documentation navigation so that developers can easily navigate to definitions.

My Background
I am a Full Stack Blockchain Developer with proficiency in Solidity/Rust, Next.js, TypeScript, React, and Node.js. I've demonstrated my ability to adjust to a variety of requirements, perform well under pressure, and reliably produce user-centric blockchain solutions with 46 significant contributions spread over 10 OnlyDust projects.

[mimisavage]

Let me try this one!

[abdegenius]

I’d like to resolve this. Would love to tackle this! I can comfortably handle this issues

[caxtonacollins]

Is it okay if I tackle this?

[Benjtalkshow]

I’d like to resolve this.

[ShantelPeters]

Can I contribute to this one?

I will adopt JSDoc/TSDoc standards to document the web3 package by adding standardized comments to all functions, classes, parameters, and return types, then use tools like typedoc or jsdoc to generate and validate comprehensive documentation for improved maintainability and onboarding.

[pheobeayo]

Could I grab this task?
I am a Web3 front-end developer skilled in technical documentation and software development. I greatly understand technologies like JavaScript, Typescript, Cairo, Rust and Solidity. I have contributed successfully to open-source projects like Stark Quest and Speedrun scaffold-stark.

How I plan to tackle this
My Approach includes:

• Reviewing of existing Documentation:
  By thoroughly reading the current documentation, including README files, code comments, and any other relevant documentation provided in the repository.
  -Identify areas that are unclear, outdated, or missing crucial information that would benefit users and developers.
• Write a well-structured template containing the needed information using the correct references using the JSDoc or TSDoc standard.
• Note changes and define all code snippets and technical terms simply.
• Create a Pull Request (PR)
• Request for a Review
• Make changes based on the Review of the PR.

[mimiprosper]

Am a web 2 frontend developer, a smart contract developer/auditor and technical writer. I understand the importance of good and concise documentation in software development. I have participated successfully in OD Hack task assigned to me. I have written many technical articles, here are some of them, https://medium.com/@emma.onyedika.okeke

I would use SDoc and/or TSDoc standard to improve your code base readability, provide a standardized way to document functions, classes, parameters, return types, and modules, making it easier to generate comprehensive, up-to-date documentation. I would conclude this task in 7 days if assigned this task.

[Iwueseiter]

May I handle this issue?
Here are links to comprehensive docs I've written and have been merged Flex-NFT-Marketplace/Flex-Marketplace-Contract#107, cairo-book/cairo-book#1019, horuslabsio/tokenbound-contract-docs#12, sivicstudio/starkludo#102, https://hackmd.io/@-__sK8xkRjuXHkFZQLyYXg/HkLcMImM1l.

[Supa-mega]

I'd like to handle this task.

[vestor-dev]

hey sir I'd like to handle this task.
i'm a frontend developer and a blockchain dev
i would really love to contribute to your project
please kindly assign :)

[Kaminar-i]

Mind if I take this issue?
i'm new and would love to work on this