Re-consider having API docs for certain packages

[arboleya]

At first, we spoke about eliminating Typedocs completely because the majority of files are not documented, and displaying purely mechanical and hollow documentation only adds noise, burying the rest underneath it.

However, a few places might have relevant docs to show.

These docs could be:

1. Incorporated in the Guide in .md format (typedocs stay out)
2. Re-enabled and put in a different menu section (typedocs returns)

Either way, we must first understand what packages fall in this category.

Then we can see what to do.

[arboleya]

@luizstacio Want to chime in and list the packages you had in mind?

cc @Torres-ssf @FuelLabs/sdk-ts

[danielbate]

I would like to see API documentation for certain packages within the TS SDK. Contextualised documentation and cookbooks (as we have currently) goes hand in hand with API documentation, and something I usually expect some level of with complex libraries. Done properly as well this is something that can just work alongside us as well rather than adding unnecessary overhead.

At a high level, I would like to see the entry point classes and methods documented for our core packages, as well as the parameters and config that they require, this could include:

• Contract interaction, contract factory, methods to call contracts and the configuration / parameters required
• Predicate instantiation within the SDK, transactional methods with predicates and setting data / configurables
• Providers and it's methods, then coins, messages and resources (do we want to expose the GQL schema and autogenerated types here?)
• Transactions including ScriptTransactionRequest and building out custom transactions (i.e. the methods available to the transaction request classes and params they expect, and any potential config)
• Wallets, different types of wallet and the functions available to those types
• Address, different types of addresses and the helpers to convert between them

I agree with the above points that it should be under a separate menu item to our current documentation menu items. I also think it is easier to maintain as it is directly to our business logic when using something like typedoc. And then easily incorporated to vitepress by outputting markdown.

I also agree with trying to reduce noise in code. We should do this in iterations, at first I would like to see the above just referenced and documented, potentially without any additional explanation to what is already available to us when highlighting functions in IDEs. Any additional noise could be added using type doc references?

[arboleya]

@danielbate Thanks. Each of these bullet points can become an individual task. The first task should also add back typedocs and integrate it with vitepress in the current build routine.

@Torres-ssf I can't remember — did we make any progress experimenting with typedocs x vitepress in the past?

[danielbate]

@arboleya @Torres-ssf I'd be happy to take those on 👍🏻 I can write up some tasks later on also

[Torres-ssf]

@arboleya, When we switched to Vitepress as our Doc engine, I didn't find a good native integration with Typedocs.

However, there might be improvements since then.

[danielbate]

To reimplement API docs in the TS SDK documentation, the following tasks should be completed:

• Create a proof of concept that integrates typedoc within vitepress whilst documenting the Address package and is built with vitepress documentation and does not sit along side source code
  • feat: implement typedoc in vitepress #1115
• Purge unwanted files generated by docs tools
  • feat: add docs script to remove unwanted files #1139
• Restructure typedoc directories to support docs hub
  • feat: restructure typedoc directories to support the docs hub #1155
• Integrated with the program and contract packages to document contract instantiation and configuration
  • feat: implement TypeDoc in Contract #1167
  • feat: implement TypeDoc in Program #1174
• Integrated with the predicate package to document predicate instantiation and configuration
  • feat: implement TypeDoc in Predicate #1163
• Integrated with the script package to document predicate instantiation and configuration
  • feat: implement TypeDoc in Script #1165
• Integrated with the provider package to document provider based operations and inputs/outputs, as well as building out transactions
  • feat: implement TypeDoc in Provider #1178
• Integrated with wallet package to document the various wallet types and their instantiations
  • feat: implement TypeDoc in Wallet #1162
• Typedoc links are automatically generated within the vitepress config
  • feat: restructure typedoc directories to support the docs hub #1155
• Autogenerated internal links built via filesystem rather than hardcoded
  • feat: automate Typedoc link regeneration in API docs #1180

[sarahschwartz]

For the docs hub, please make sure that the generated API subfolders and file names match the navigation names and structure.

[danielbate]

Closing this as we have now reimplemented TypeDoc for API documentation. Will open further issues for changes and amendments.