Improve JSDocs by adding examples of usages

[ivpavici]

Inspired by Viem docs, example:

https://viem.sh/docs/accounts/privateKey#usage

This is a big endeavor so it can be completed in multiple smaller PR-s (and more users can take it in parallel!)

IMPORTANT: add @example only to exported functions

TODO utils:

• [ ] src/utils/calldata/validate
• [ ] src/utils/calldata/formatter
• [ ] src/utils/calldata/propertyOrder
• [ ] src/utils/calldata/requestParser
• [ ] src/utils/calldata/responseParser
• [ ] src/utils/calldata/tuple
• [ ] src/utils/calldata/parser/index.ts
• [ ] src/utils/events/index.ts
• [ ] src/utils/hash/classHash.ts
• [ ] src/utils/hash/transactionHash/v3.ts

[ivpavici]

Users please pick one part of the docs which you want to work on and write here for everyone else to know!

[elielnfinic]

Hey @ivpavici, could you please specify on which elements examples should be added ?

[Ayoazeez26]

I would love to take the signature part of the docs

[Jemiiah]

if this work isn't assigned to anybody, can i get it, @ivpavici ?

[ivpavici]

hi all!

To explain a bit more, we are not talking about rewriting Guides (like https://www.starknetjs.com/docs/guides/create_account) but adding examples to JSdocs in the code, how they can be used, for example on utils:

which looks like this:

[ivpavici]

This means you need to try out, play and test some parts of the code, to see how it works and then add an example. Some of them can be for sure found in tests and will be easy to solve!

[ivpavici]

@Jemiiah no need to assign since multiple people can work on it... pick a part of the code (please write here which) and send a PR with this issue linked

[Ugo-X]

Hello @ivpavici would like to handle the Estimate fees segment, if there's no need for an assignment won't there be a clash at some point?

[ivpavici]

@Ugo-X I will consider PR-s from contributors who announce the parts up front. Also, you can open an issue yourself and I can assign you! and link the issue here

[fishonamos]

Hi @ivpavici I will love to work on typeData.ts and json.ts

[BlackStarkGoku]

Hello I would like to contribute, I hope I understood well the task, I will try to write the exemples of the address.ts file.

[Iwueseiter]

@ivpavici can i work on TS Config.json and signer/interface.ts

[ivpavici]

PR by @BlackStarkGoku is a good example to take a look in what direction we want to go: https://github.com/starknet-io/starknet.js/pull/1096

[BlackStarkGoku]

Perfect thanks @ivpavici then I will add more such as encode.ts, num.ts

[NueloSE]

@ivpavici can I work on num.ts

[ivpavici]

ok, please @BlackStarkGoku can you leave num.ts to @NueloSE

[BlackStarkGoku]

Ok I will just do encode.ts for now

[petersdt]

@ivpavici can i work on shortString.ts and transaction.ts

[NueloSE]

Hi @ivpavici num.ts has been approved.

Can i take go on with the following issues: uint256 , merkle.ts and selectors

[ivpavici]

@NueloSE thanks! go for it!

[CollinsC1O]

@ivpavici can i work on url.ts

[vibenedict]

I would like to work on hash and provider

[muheebyusufbaba1]

Can I go with stark.ts, starknetid.ts, and connect.ts

[Osatuyi]

Hi, @ivpavici can I work on index.ts and propertyOrder.ts

[ivpavici]

hey all! It is fine to use ChatGPT to help, but it doesn't make sense to push a ChatGPT generated PR without testing and trying to understand the examples in the docs Please test all the examples before submitting

[github-actions[bot]]

:tada: This issue has been resolved in version 6.9.0 :tada:

The release is available on:

• npm package (@next dist-tag)
• GitHub release

Your semantic-release bot :package::rocket:

[KeneePatel]

Hey @ivpavici,

Just wanted to confirm if we are still open to add docs in the code. If yes, I will start on testing some functions and add documentation to it. I had a look at the code and saw some undocumented functions in shortString.ts. So, if you allow I will start to look for more, test them out, add docs and examples to them.

[ivpavici]

@KeneePatel hello! in the next-version branch we addressed the shortString functions... But feel free to take any other that are not yet addressed (or in a pending PR)

[johnkennedyb]

@ivpavici ,can I take on transaction.test.ts and contract.test.ts

[PedroCo3lho]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I'm a developer who have worked with web and mobile development, recently i'm walking trough web3 development starting with Starknet. i've contributed to some web3 projects and integrate some wallets.

How I plan on tackling this issue

With my programming experience i can understand data flows and code architecture that make add examples in starknet.js clear and suitable to my profile

[ivpavici]

@PedroCo3lho feel free, although please test your solution - we will not accept a PR without proper testing!

[github-actions[bot]]

:tada: This issue has been resolved in version 7.0.0 :tada:

The release is available on:

• npm package (@next dist-tag)
• GitHub release

Your semantic-release bot :package::rocket:

[JovanMwesigwa]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I am a blockchain developer with a robust technical background and extensive experience in creating educational content for the blockchain community. Over the years, I have published more than 20 technical blogs on various blockchain topics, which can be found here - https://celo.academy/u/jovan/activity/topics. These publications demonstrate my ability to break down complex concepts into easily digestible content, a skill that will be valuable in enhancing the Starknet JS documentation.

Additionally, I have developed a comprehensive portfolio showcasing my work and tutorials, available https://unrealjoova.vercel.app/tutorials. This portfolio reflects my hands-on experience with blockchain technology and my commitment to sharing knowledge with the developer community.

Currently, I am the co-founder of OneRamp https://oneramp.io, where we focus on making blockchain technology more accessible to users and developers alike. My role involves not only development but also creating clear and concise documentation and user guides, ensuring our solutions are user-friendly and well-documented.

My technical writing skills, combined with my deep understanding of blockchain technology, make me well-suited to contribute to the Starknet JS repository. I am confident that I can improve the documentation by incorporating small code snippets and examples, making it easier for developers to understand and utilize Starknet JS.

You can find more about my professional background and connect with me on my social profiles:

• LinkedIn: https://www.linkedin.com/in/jovan-mwesigwa
• Twitter: https://x.com/unreal_joova

I look forward to the opportunity to contribute to Starknet JS and help enhance its documentation for the benefit of the developer community.

How I plan on tackling this issue

To approach the problem of improving the Starknet JS documentation, I would follow a structured and iterative process:

1. Assessment and Planning a. Review Existing Documentation:

   • Conduct a thorough review of the current Starknet JS documentation to understand its structure, content, and areas needing improvement. Identify gaps, inconsistencies, and outdated information.

2. Content Development a. Create a Documentation Plan:

   • Develop a detailed plan outlining the structure of the documentation, including sections like Getting Started, Tutorials, API Reference, Examples, and Troubleshooting. Define the scope and sequence of content to be updated or added.

3. Implementation and Integration a. Use GitBook for Documentation:

   • Set up GitBook as the platform for hosting and managing the documentation. GitBook's features like real-time collaboration, version control, and integration with GitHub will streamline the process. Migrate the existing documentation to GitBook and organize it according to the new structure.

4. Maintenance and Updates a. Regular Updates:

   • Establish a process for regularly updating the documentation to reflect changes in Starknet JS and new features. Encourage contributions from the community to keep the documentation current and comprehensive.

[adriansb3105]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I am a 4-year-old software developer, and passionate about this great technology which is Web3. What I wish is for every developer to be close to it the same as I was.

How I plan on tackling this issue

I will create several real-world test applications to have useful use cases in order to improve the documentation with real examples that people can understand and use.

[ALverlaine]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I am in the final six months of my Computer Science master's degree at UCLouvain in Belgium thus I am starting to seek opportunities, and a friend who already finished university introduced me to StarkNet so here i am :). I think i have enough skills to add some example to the usage of some functions, i am more here as an entry point to be more familiar with StarkNet.

How I plan on tackling this issue

The first thing I would do, since I am new to this, would be to understand how the function works. If possible, I would test it and then see what we can do with it and its purpose in the code. I think by this point, the examples of usage will become clearer.

[HumbertoTM10]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I'm a software developer with experience in Web2 projects, I'm getting more into the Web3 world and will be pleased to contribute in the project.

How I plan on tackling this issue

I will get into the current docs to understand the right functioning in order to provide concise examples.

[mohit-100]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I am a MERN stack developer with a strong focus on React development and experience in building scalable web and mobile applications. My work on various projects, including e-commerce platforms and LMS systems, has honed my skills in both front-end and back-end technologies. I am proficient in Node.js, Express.js, AWS serverless, and Docker CI/CD, with a growing interest in blockchain technology. My ability to deliver comprehensive solutions makes me a strong fit for innovative projects that require a blend of technical expertise and creativity

How I plan on tackling this issue

My approach to problem-solving begins with thoroughly understanding the problem, clarifying any unclear requirements, and identifying constraints. I then break the problem into smaller, manageable components, prioritizing tasks based on impact. After researching and exploring potential solutions, I choose the best approach, often starting with a prototype. I iterate and refine the solution based on feedback and thorough testing. Finally, I ensure that the process is well-documented for future reference and continuous improvement

[martinvibes]

hello @ivpavici I would love to participate on this if i'm giving the opportunity :)

[RuneRogue]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I am a blockchain and DeFi developer . I am having experience of 8 months . I am currently working as a Blockchain Researcher and Developer. My Experience in programming language like Go , Rust , Java will help me to solve this issue.

[Tushar4059x]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

i wanna work on this issue

How I plan on tackling this issue

trust me i'm good with js ;)

[deeseeker]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I’m a React developer with over two years of experience in JavaScript and TypeScript, with a strong focus on writing clean and maintainable code. My background in frontend development has given me extensive experience in optimizing code documentation and enhancing the developer experience. Recently, I've been exploring Starknet, and this open issue caught my attention. While I’m still learning about blockchain technology, I’m excited to tackle this challenge and contribute to making the learning process smoother for others as well.

How I plan on tackling this issue

Clone the project on my pc Spin it up following the documentation Review the existing codebase to understand the functionalities of the exported functions in the specified utils. I plan to create usage examples that cover common use cases and edge cases.

I would break down the task into smaller, manageable PRs, focusing on one or two files at a time.

I would coordinate with other contributors to avoid overlap and ensure that all relevant functions are covered.

[martinvibes]

hello @ivpavici is any of the jsdoc issues still remaining? would love to work on one :)

[Kaminar-i]

hello @ivpavici please can i also be assigned?

[llamitaOnfire]

Hi @ivpavici just created the issue https://github.com/starknet-io/starknet.js/issues/1225 to take the propertyOrder section. Can you assign it to me?

[LuisDi98]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

I'm a software engineer, already checked BlackStarGoku documentation and I want to take the requestParser documentation section.

How I plan on tackling this issue

I created an issue as mentioned before, please assign it to me. Issue: https://github.com/starknet-io/starknet.js/issues/1226

[Benjtalkshow]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged

Hello, I am available to work on this. ETA: 48hrs

[ivpavici]

Hi all! We no longer have a budget for external contributions currently...

Thanks for reaching out though, if we get more funds I will open new issues!