search

hyperledger-solang / solang

Solidity Compiler for Solana and Polkadot
https://solang.readthedocs.io/
Apache License 2.0
1.26k stars 210 forks source link

Improve docs.rs documentation #1158

Open brockelmore opened 1 year ago

brockelmore commented 1 year ago

Describe the bug Currently, documentation is a read-the-docs style documentation. This kinda sucks for consumers of this as a library (i.e. Foundry, etc) because rust devs are used to docs.rs style. Forcing users to clone the repo and run cargo doc --open is less than ideal

To Reproduce Steps to reproduce the behavior:

  1. go to the documentation site

Expected behavior Alternatively or additionally publish docs to docs.rs

Screenshots N/A

Hyperledger Solang version N/A

Include the complete solidity source code N/A

Additional context N/A

xermicus commented 1 year ago

We do not link to it on crates.io, but that doesn't mean it is not on docs.rs.

However, please keep in mind, providing a stable and well-documented API for 3rd-party projects (except for our solang-parser lib) is currently work in progress.

seanyoung commented 1 year ago

The rustdoc is very incomplete. The solang crate does not have any crate level documentation, nor does solang-parser. This can certainly be improved. There are many functions, enums and structs which do not have documentation. The solang-parser crate does not have a README.md either, which looks bad on crates.io.

The rustdoc should describe how solang can be used as a crate. The documentation for the solidity language does not belong in the rust doc, but it certainly must be linked from rustdoc.

This issue should cover improving the overall rustdoc experience, without merging the readthedocs documentation. There is a clear separation between the solidity language and the using the compiler crate.