search

alephium / alephium-web3

The Typescript SDK for building dapps on Alephium
GNU Lesser General Public License v3.0
11 stars 26 forks source link

Enhance Documentation Using JSDoc/TsDoc Standards #444

Open h0ngcha0 opened 1 week ago

h0ngcha0 commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

Hey @alanJames00, those requirements are excellent!

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

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 commented 1 week ago

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

Michaelkingsdev commented 5 days ago

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

Mystic-Nayy commented 4 days ago

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 https://github.com/dragan2234/worldcoin-scroll-bridge/pull/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 commented 4 days ago

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

0xdevcollins commented 4 days ago

@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 commented 4 days ago

Let me try this one!

abdegenius commented 4 days ago

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

caxtonacollins commented 4 days ago

Is it okay if I tackle this?

Benjtalkshow commented 4 days ago

I’d like to resolve this.

ShantelPeters commented 4 days ago

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 commented 4 days ago

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:

mimiprosper commented 4 days ago

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 commented 4 days ago

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, https://github.com/cairo-book/cairo-book/pull/1019, https://github.com/horuslabsio/tokenbound-contract-docs/pull/12, https://github.com/sivicstudio/starkludo/pull/102, https://hackmd.io/@-__sK8xkRjuXHkFZQLyYXg/HkLcMImM1l.

Supa-mega commented 4 days ago

I'd like to handle this task.

vestor-dev commented 4 days ago

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 commented 4 days ago

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