Skip to content

Conversation

@Kriskras99
Copy link
Contributor

TODO:

  • Proofread everything
  • Split the Clippy lints and fixing them into a separate commit

The first page of our documentation was overwhelmingly large. This commit moves the documentation to several places:

  • The introduction to Avro itself was moved to documentation::primer
  • Using the crate the "Avro" way was moved to documentation::generic
    • I've also changed the focus to the fact that it allows for more dynamic code
  • Using the crate the "Serde" way was moved to serde
  • Calculating schema fingerprints was moved to Schema::fingerprint
    • Users can easily find it by searching for fingerprint
  • Custom name validators was moved to validator
    • Can be found via search and listed under the modules on the first page
  • Custom schema equality was moved to schema_equality
    • Can be found via search and listed under the modules on the first page It also removes some sections
  • How to install the library and enable features, this is basic Rust knowledge
  • Section about breaking changes in minor versions, this is to be expected as the crate is at 0.*
  • Reading and writing logical types, this was a very large section but not very useful
  • Ill formed data, instead the error message was improved by adding a link to the function to change the limit

This also adds documentation for the AvroSchema derive (on the trait) and updates the derive crate documentation to link to it.

In addition, I've enabled some Clippy lints related to documentation and fixed all the lints it caused.

Future work:

  • Enable the clippy.missing_errors_doc and clippy.missing_panics_doc lints
  • Deprecate some types that live in the root namespace
    • For example, the codec related types. Instead the codec module should be public
    • This will further improve the signal to noise ratio on the first page

@Kriskras99 Kriskras99 marked this pull request as draft February 1, 2026 22:05
@Kriskras99 Kriskras99 force-pushed the feat/documentation branch 2 times, most recently from dc07230 to b1f461c Compare February 2, 2026 07:45
[The first page of our documentation](https://docs.rs/apache-avro/0.21.0/apache_avro/) was
overwhelmingly large. This commit moves the documentation to several places:
 - The introduction to Avro itself was moved to `documentation::primer`
 - Using the crate the "Avro" way was moved to `documentation::generic`
   - I've also changed the focus to the fact that it allows for more dynamic code
 - Using the crate the "Serde" way was moved to `serde`
 - Calculating schema fingerprints was moved to `Schema::fingerprint`
   - Users can easily find it by searching for fingerprint
 - Custom name validators was moved to `validator`
   - Can be found via search and listed under the modules on the first page
 - Custom schema equality was moved to `schema_equality`
   - Can be found via search and listed under the modules on the first page
It also removes some sections
 - How to install the library and enable features, this is basic Rust knowledge
 - Section about breaking changes in minor versions, this is to be expected as the crate is at `0.*`
 - Reading and writing logical types, this was a very large section but not very useful
 - Ill formed data, instead the error message was improved by adding a link to the function to change the limit

In addition, I've enabled some Clippy lints related to documentation and fixed all the lints
it caused.

Future work:
 - Enable the `clippy.missing_errors_doc` and `clippy.missing_panics_doc` lints
 - Deprecate some types that live in the root namespace
   - For example, the codec related types. Instead the `codec` module should be public
   - This will further improve the signal to noise ratio on the first page
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants