Docs: Many crates are poorly documented and very limited examples

[zilayo]

Problem

Originally posted in anza-xyz/agave (anza-xyz#315), but unclear which repo is the "main" solana repo going forward, so cross posting here.

A lot of current Solana crates are missing documentation, and have very limited examples.

This provides a barrier to becoming acquainted with the codebase and can lead to uncertainty when importing items from these crates as dependencies.

Also may lead to bugs due to developers misunderstanding the intended behavior of pieces of code.

Similar concerns have been raised previously #23740

Raising this so that it can be tracked.

Current doc coverage

Here's a few examples from the most downloaded solana crates per crates.io.

solana_sdk_macro - 18% documented
solana_frozen_abi - 0% documented
solana_program - 52% documented
solana_logger - 20% documented
solana_sdk - 64% documented
solana_metrics - 26% documented
solana_config_program - 39% documented
solana_vote_program - 27% documented
solana-transaction-status - 5% documented
solana_account_decoder - 2% documented
solana_clap_utils - 12% documented
solana_remote_wallet - 23% documented
solana_client - 30% documented

A few crates do already have 100% doc coverage, and we should strive to make sure this is the case for all crates.

Proposed Solution

Ideally all crates should have doc comments for all public structs, methods, enums etc - leading to 100% doc coverage.

Given the large codebase, this can be broken down into several PRs, each targeting a specific crate.

Once a crate's public items have been fully documented, the rule #![deny(missing_docs)] could be applied to ensure that future additions will always include documentation.

[github-actions]

This repository is no longer in use. Please re-open this issue in the agave repo: https://github.com/anza-xyz/agave