Conversation
[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
WalkthroughThis pull request refactors documentation and expands several public APIs within the Avro Rust crate. Changes include: two new Clippy lint rules in Cargo.toml; substantial README reduction with streamlined content; new public deprecation-wrapper functions in bytes.rs for compatibility; introduction of cfg(doc)-gated documentation modules (dynamic.rs and primer.rs) containing usage examples and conceptual guides; additions to the Schema enum with new variants; new schema compatibility methods (can_read and mutual_read); validator registration functions now returning Result instead of unit; and widespread documentation comment updates improving clarity, formatting, and cross-references across the codebase. The changes balance API surface expansion with comprehensive documentation restructuring. ✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @martin-augment, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request focuses on a comprehensive documentation rework to enhance the clarity, organization, and overall user experience of the project. It involves migrating detailed content into new, structured documentation modules, refining existing doc comments for better readability and accuracy, and introducing new static analysis checks to maintain high documentation standards. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
PR Review: Documentation ReworkOverall Assessment: ✅ EXCELLENT - Strongly Recommend ApprovalThis is a high-quality documentation refactoring that significantly improves the user experience without introducing any bugs or API changes. The PR successfully transforms scattered, redundant documentation into a well-organized, maintainable structure. SummaryChanges: 1,218 additions / 1,983 deletions across 32 files Key Improvements1. New Documentation Module Structure ⭐The PR introduces a new
This is excellent separation of concerns - getting-started content is now distinct from API reference. 2. Simplified lib.rs ⭐⭐⭐The top-level crate documentation was reduced from ~900 lines to ~36 lines:
3. README.md CleanupRemoved ~750 lines of duplicated content, now properly focused on high-level overview and directing users to docs.rs. 4. Enhanced Module Documentation ⭐⭐
5. Documentation Quality Improvements Throughout
6. Clippy Lint ConfigurationAdded documentation quality lints to maintain standards going forward:
Issues Found🐛 Minor Bug: Typo in Documentation LinkFile: //! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader),
//! [`GenericSingleObjectWriter`](crate::GenericSingleObjectReader), // ← Should be GenericSingleObjectWriter
The second link incorrectly points to Fix: Change line 73 to: //! [`GenericSingleObjectWriter`](crate::GenericSingleObjectWriter),
Code Quality Analysis✅ No bugs introduced - Pure documentation changes Performance ConsiderationsN/A - Documentation-only changes have no runtime performance impact. Security ConcernsNone - No code logic changes. Test Coverage✅ Documentation examples use doc-test syntax - Many examples include the Recommendations
Impact AssessmentFor New Users:
For Existing Users:
For Maintainers:
Final Recommendation✅ APPROVE (after fixing the minor typo) This PR represents exactly the kind of documentation improvement that makes a library more accessible and maintainable. The reduction in total line count while improving clarity is a testament to the quality of the refactoring. Great work! 🎉 Review generated by Claude Code |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request is a significant and well-executed rework of the documentation for the apache-avro crate. The changes improve clarity, add helpful examples, and restructure the documentation to be more modular and user-friendly. Key improvements include adding detailed module-level documentation for serde, schema_compatibility, schema_equality, and custom validators, as well as greatly expanding the documentation for the AvroSchema derive macro. The main README.md and lib.rs have been simplified to provide a better entry point for new users, directing them to the more detailed documentation modules. I've found one minor issue with a broken link in the new documentation.
| //! [`TryFrom<Value> for serde_json::Value`](crate::types::Value) implementations. | ||
| //! | ||
| //! ## Compression | ||
| //! For records with low entropy it can be useful to compress the encoded data. Using the [#Object Container File] |
There was a problem hiding this comment.
The link [#Object Container File] appears to be broken. It will likely render as a link to the top of the page. To link to the 'Object Container File' section within this document, you should use a standard markdown anchor link. The correct anchor for the section header #### [Object Container File](...) is #object-container-file.
For records with low entropy it can be useful to compress the encoded data. Using the [Object Container File](#object-container-file)There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The Claude AI reviewer is correct! There is a broken link to an earlier section that needs to be fixed. Prevents having a wrong link in the documentation.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🤖 Fix all issues with AI agents
In `@avro/README.md`:
- Around line 45-59: The README uses rustdoc intra-doc links (e.g.,
documentation::primer, types::Value, serde) which won't render as clickable on
GitHub/crates.io; update avro/README.md to replace those intra-doc links with
full external URLs (for example point Value to its docs.rs page and
documentation::primer to the docs.rs primer section) or add parallel Markdown
links alongside the rustdoc links so the README shows clickable links on
GitHub/crates.io while preserving the rustdoc-style references for docs.rs.
In `@avro/src/documentation/dynamic.rs`:
- Line 164: Fix the documentation typo by removing the extra space in the phrase
"Result of" so it reads "Result of"; search for the exact substring "Result
of" in dynamic.rs (the doc comments around the Avro Value/read operation) and
replace both occurrences (one at the shown comment and the other around line
213) so the doc comments correctly say "Result of".
In `@avro/src/documentation/primer.rs`:
- Around line 72-74: The doc comment incorrectly links GenericSingleObjectWriter
to the reader type; update the documentation line to reference the correct
writer type path (replace
[`GenericSingleObjectWriter`](crate::GenericSingleObjectReader) with
[`GenericSingleObjectWriter`](crate::GenericSingleObjectWriter)) so the rendered
docs point to the writer, and verify the other three links
(`SpecificSingleObjectReader`, `SpecificSingleObjectWriter`, and
`GenericSingleObjectReader`) remain correct.
- Around line 55-105: Replace all occurrences of the literal "++version++" in
the spec URLs with a resolvable spec path (e.g. "current" or the actual spec
version) so the links render in rustdoc; change the invalid intra-doc link label
"[`#Object` Container File]" to a proper reference-style anchor (e.g.
"object-container-files" or the lowercase-hyphen form used by rustdoc) wherever
the Object Container File section is referenced; and fix the grammar in the Avro
JSON paragraph by changing "Not be confused with the schema definition which is
also in JSON." to a proper sentence (e.g. "Do not be confused with the schema
definition, which is also in JSON."). Use the surrounding symbols to find
locations: the spec URLs, the "[`#Object` Container File]" reference, and the
"Avro JSON" paragraph that mentions From<serde_json::Value> for Value and
TryFrom<Value> for serde_json::Value.
In `@avro/src/schema/mod.rs`:
- Line 110: Update the doc comment that currently reads "A `array` Avro schema."
to use the correct indefinite article by changing it to "An `array` Avro
schema." — locate the docstring attached to the Avro array schema (the comment
adjacent to the Array variant/struct in mod.rs) and replace "A `array`" with "An
`array`".
- Around line 941-943: Fix the typo in the module doc comment: change the link
label "[the Parsing Canonical From]" to "[the Parsing Canonical Form]" so it
matches the earlier reference "[the Parsing Canonical Form]" and restores the
doc link. Locate the comment block in avro/src/schema/mod.rs that documents
parsing (the doc lines containing "[the Parsing Canonical Form]") and update the
spelled word "From" to "Form" in the link definition.
In `@avro/src/schema/parser.rs`:
- Line 538: Several doc comments in parser.rs use the incorrect article "a
Avro"; change those occurrences to "an Avro". Edit the doc comment that
currently reads "Parse a `serde_json::Value` representing a Avro record type
into a `Schema`" (the comment above the function that parses a serde_json::Value
into a Schema) and the other doc comments flagged (around the parser functions
that describe parsing Avro types such as record/union/named types) to use "an
Avro" instead of "a Avro".
- Around line 68-70: Update the doc comment in avro/src/schema/parser.rs that
currently reads "Create an array of `Schema`'s from an iterator of JSON Avro
schemas." to use the correct plural form "Schemas" (e.g., "Create an array of
Schemas from an iterator of JSON Avro schemas."). Locate the doc comment above
the parser functionality that documents creating an array of Schema values and
replace the possessive "Schema`'s" with the plain plural "Schemas" so the
comment reads grammatically correct.
In `@avro/src/validator.rs`:
- Around line 38-43: Update the documentation example so it does not ignore the
Result returned by set_schema_name_validator; locate the example around
set_schema_name_validator(Box::new(MyCustomValidator)) and change it to handle
the Result (for example by checking is_err() and handling the "validator already
registered" case or propagating the error) so users following the docs won't hit
an #[must_use] warning.
🧹 Nitpick comments (2)
avro/src/serde/derive.rs (2)
72-73: TODO comment will render in generated documentation.The
// TODO:comment on line 72 is inside the doc block and will appear in the generated documentation. If this is intended as an internal note, consider moving it outside the doc comment or converting it to a proper doc note.🔧 Suggested fix
-// TODO: Should we check if `name` contains any dots? As that would imply a namespace -/// Set the `name` of the schema to the given string. Defaults to the name of the type. +/// Set the `name` of the schema to the given string. Defaults to the name of the type.Or if you want to keep the note visible:
-// TODO: Should we check if `name` contains any dots? As that would imply a namespace -/// Set the `name` of the schema to the given string. Defaults to the name of the type. +/// Set the `name` of the schema to the given string. Defaults to the name of the type. +/// +/// _Note: Names containing dots imply a namespace._
94-96: Minor grammar issue in documentation."only unskipped field" should be "only one unskipped field" for grammatical correctness.
📝 Suggested fix
-/// Use the schema of the inner field directly. Is only allowed on structs with only unskipped field. +/// Use the schema of the inner field directly. Is only allowed on structs with only one unskipped field.
| **[Apache Avro](https://avro.apache.org/)** is a data serialization system which provides rich | ||
| data structures and a compact, fast, binary data format. If you are not familiar with the data | ||
| format, please read [`documentation::primer`] first. | ||
|
|
||
| #[derive(Debug, Deserialize, PartialEq, Serialize)] | ||
| struct ExampleByteArray { | ||
| #[serde(with = "apache_avro::serde::bytes_opt")] | ||
| data_bytes: Option<Vec<u8>>, | ||
| description: Option<String>, | ||
| } | ||
| There are two ways of working with Avro data in this crate: | ||
|
|
||
| fn serde_byte_array() { | ||
| let raw_schema = r#" | ||
| { | ||
| "type": "record", | ||
| "name": "SimpleRecord", | ||
| "fields": [ | ||
| {"name": "data_bytes", "type": ["null", "bytes"], "default": null}, | ||
| {"name": "description", "type": ["null", "string"], "default": null} | ||
| ] | ||
| }"#; | ||
| 1. Via the generic [`Value`](types::Value) type. | ||
| 2. Via types implementing `Serialize`, `Deserialize`, and [`AvroSchema`]. | ||
|
|
||
| let schema = apache_avro::Schema::parse_str(raw_schema).unwrap(); | ||
| The first option is great for dealing with Avro data in a dynamic way. For example, when working | ||
| with unknown or rapidly changing schemas or when you don't want or need to map to Rust types. The | ||
| module documentation of [`documentation::dynamic`] explains how to work in this dynamic way. | ||
|
|
||
| // Create vector of ExampleByteArray | ||
| let records = vec![ | ||
| ExampleByteArray { | ||
| data_bytes: Some(vec![1, 2, 3, 4, 5]), | ||
| description: Some("First record".to_string()), | ||
| }, | ||
| ExampleByteArray { | ||
| data_bytes: None, | ||
| description: Some("Second record".to_string()), | ||
| }, | ||
| ExampleByteArray { | ||
| data_bytes: Some(vec![10, 20, 30]), | ||
| description: None, | ||
| }, | ||
| ]; | ||
| The second option is great when dealing with static schemas that should be decoded to and encoded | ||
| from Rust types. The module documentation of [`serde`] explains how to work in this static way. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's look at the actual content of avro/README.md around lines 45-59
cat -n avro/README.md | sed -n '40,65p'Repository: martin-augment/avro-rs
Length of output: 1464
🏁 Script executed:
# Check if cargo-rdme is used in the project
fd -t f Cargo.toml | xargs grep -l "cargo-rdme\|rdme" 2>/dev/nullRepository: martin-augment/avro-rs
Length of output: 50
🏁 Script executed:
# Look for any documentation about cargo-rdme configuration
find . -name "*.toml" -o -name "*.md" | xargs grep -l "rdme" 2>/dev/null | head -5Repository: martin-augment/avro-rs
Length of output: 82
🏁 Script executed:
# Check the lib.rs file to see if these modules exist and how they're documented
cat -n avro/src/lib.rs | head -100Repository: martin-augment/avro-rs
Length of output: 4325
🏁 Script executed:
# Look for cargo-rdme configuration in the project
find . -name "Cargo.toml" -exec grep -A 10 "\[package\]" {} + | grep -A 10 "avro"Repository: martin-augment/avro-rs
Length of output: 2773
🏁 Script executed:
# Search for documentation about these modules to understand the link structure
rg -n "mod documentation|mod serde" avro/src/ | head -10Repository: martin-augment/avro-rs
Length of output: 444
🏁 Script executed:
# Check if there's a build.rs or any cargo-rdme specific configuration
ls -la avro/ | grep -E "build\.rs|cargo-rdme"Repository: martin-augment/avro-rs
Length of output: 48
🏁 Script executed:
# Check if there's documentation about how cargo-rdme works in this repo
find . -name "*.md" | xargs grep -l "cargo-rdme" 2>/dev/nullRepository: martin-augment/avro-rs
Length of output: 82
🏁 Script executed:
# Look for any GitHub workflow or CI configuration that might use cargo-rdme
find . -path "./.github/workflows" -name "*.yml" -o -name "*.yaml" | xargs cat 2>/dev/null | grep -A 5 -B 5 "rdme\|README" | head -30Repository: martin-augment/avro-rs
Length of output: 48
🏁 Script executed:
# Search the Cargo.toml files for any cargo-rdme configuration
find . -name "Cargo.toml" -exec grep -l "rdme" {} \;Repository: martin-augment/avro-rs
Length of output: 48
🏁 Script executed:
# Let's check what cargo-rdme does by looking at the exact output format
# First, check if there are any actual differences between lib.rs and README.md content
diff -u <(sed -n '18,32p' avro/src/lib.rs | sed 's/^\/\/ *//') <(sed -n '45,59p' avro/README.md)Repository: martin-augment/avro-rs
Length of output: 153
🏁 Script executed:
# Let's verify if these are actual intra-doc links by checking how they render
# Test what a browser or markdown parser would see
python3 << 'EOF'
# Check if the links are valid markdown or intra-doc format
test_strings = [
"[`documentation::primer`]",
"[`Value`](types::Value)",
"[`AvroSchema`]",
"[`documentation::dynamic`]",
"[`serde`]"
]
import re
# Pattern for markdown links: [text](url)
# Pattern for intra-doc links: [text] or [text](path::path)
for s in test_strings:
# Check if it matches markdown link format with a valid URL
if re.match(r'\[.+\]\(https?://', s):
print(f"{s} -> Valid markdown link (has http/https URL)")
# Check if it matches markdown link format with a non-URL path
elif re.match(r'\[.+\]\([^)]+\)', s):
print(f"{s} -> Markdown link with non-URL path (won't work on GitHub/crates.io)")
# Check if it's just backtick-wrapped text in brackets
elif re.match(r'\[\`.+`\]$', s):
print(f"{s} -> Intra-doc link syntax (will appear as plain text)")
else:
print(f"{s} -> Unrecognized format")
EOFRepository: martin-augment/avro-rs
Length of output: 447
🏁 Script executed:
# Check if the documentation module exists and is available
rg -n "pub mod documentation" avro/src/lib.rs -A 2Repository: martin-augment/avro-rs
Length of output: 129
Links using rustdoc syntax won't render as clickable on GitHub/crates.io
The intra-doc links like [documentation::primer] and markdown links with non-URL paths like [Value](types::Value) won't resolve to clickable hyperlinks when the README is displayed on GitHub or crates.io—they'll appear as plain text.
Since cargo-rdme syncs this content verbatim from lib.rs, and these links work correctly on docs.rs, this is a trade-off between keeping the README in sync and optimizing for README display. If README rendering on GitHub/crates.io is a priority, consider converting to full URLs (e.g., [Value](https://docs.rs/apache-avro/latest/apache_avro/types/enum.Value.html)) or accepting that the primary documentation location (docs.rs) displays correctly while the README shows unresolved links.
🤖 Prompt for AI Agents
In `@avro/README.md` around lines 45 - 59, The README uses rustdoc intra-doc links
(e.g., documentation::primer, types::Value, serde) which won't render as
clickable on GitHub/crates.io; update avro/README.md to replace those intra-doc
links with full external URLs (for example point Value to its docs.rs page and
documentation::primer to the docs.rs primer section) or add parallel Markdown
links alongside the rustdoc links so the README shows clickable links on
GitHub/crates.io while preserving the rustdoc-style references for docs.rs.
| //! // reader creation can fail in case the input to read from is not Avro-compatible or malformed | ||
| //! let reader = Reader::new(&input[..]).unwrap(); | ||
| //! | ||
| //! // value is a Result of an Avro Value in case the read operation fails |
There was a problem hiding this comment.
Typo: Extra space in "Result of"
-//! // value is a Result of an Avro Value in case the read operation fails
+//! // value is a Result of an Avro Value in case the read operation failsThe same typo appears on line 213.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| //! // value is a Result of an Avro Value in case the read operation fails | |
| //! // value is a Result of an Avro Value in case the read operation fails |
🤖 Prompt for AI Agents
In `@avro/src/documentation/dynamic.rs` at line 164, Fix the documentation typo by
removing the extra space in the phrase "Result of" so it reads "Result of";
search for the exact substring "Result of" in dynamic.rs (the doc comments
around the Avro Value/read operation) and replace both occurrences (one at the
shown comment and the other around line 213) so the doc comments correctly say
"Result of".
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The CodeRabbit AI reviewer is correct! There is an extra space character that needs to be removed.
| //! [the schema section of the specification]: https://avro.apache.org/docs/++version++/specification/#schema-declaration | ||
| //! | ||
| //! ## Data serialization and deserialization | ||
| //! There are various formats to encode and decode Avro data. Most formats use the Avro binary encoding. | ||
| //! | ||
| //! #### [Object Container File](https://avro.apache.org/docs/++version++/specification/#object-container-files) | ||
| //! This is the most common file format used for Avro, it uses the binary encoding. It includes the | ||
| //! schema in the file, and can therefore be decoded by a reader who doesn't have the schema. It includes | ||
| //! many records in one file. | ||
| //! | ||
| //! This file format can be used via the [`Reader`](crate::Reader) and [`Writer`](crate::Writer) types. | ||
| //! | ||
| //! #### [Single Object Encoding](https://avro.apache.org/docs/++version++/specification/#single-object-encoding) | ||
| //! This file format also uses the binary encoding, but the schema is not included directly. It instead | ||
| //! includes a fingerprint of the schema, which a reader can look up in a schema database or compare | ||
| //! with the fingerprint that the reader is expecting. This file format always contains one record. | ||
| //! | ||
| //! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader), | ||
| //! [`GenericSingleObjectWriter`](crate::GenericSingleObjectReader), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader), | ||
| //! and [`SpecificSingleObjectWriter`](crate::SpecificSingleObjectWriter) types. | ||
| //! | ||
| //! #### Avro datums | ||
| //! This is not really a file format, as it's just the raw Avro binary data. It does not include a | ||
| //! schema and can therefore not be decoded without the reader knowing **exactly** which schema was | ||
| //! used to write it. | ||
| //! | ||
| //! This file format can be used via the [`to_avro_datum`](crate::to_avro_datum), [`from_avro_datum`](crate::from_avro_datum), | ||
| //! [`to_avro_datum_schemata`](crate::to_avro_datum_schemata), [`from_avro_datum_schemata`](crate::from_avro_datum_schemata), | ||
| //! [`from_avro_datum_reader_schemata`](crate::from_avro_datum_reader_schemata), and | ||
| //! [`write_avro_datum_ref`](crate::write_avro_datum_ref) functions. | ||
| //! | ||
| //! #### [Avro JSON](https://avro.apache.org/docs/++version++/specification/#json-encoding) | ||
| //! Not be confused with the schema definition which is also in JSON. This is the Avro data encoded | ||
| //! in JSON. | ||
| //! | ||
| //! It can be used via the [`From<serde_json::Value> for Value`](crate::types::Value) and | ||
| //! [`TryFrom<Value> for serde_json::Value`](crate::types::Value) implementations. | ||
| //! | ||
| //! ## Compression | ||
| //! For records with low entropy it can be useful to compress the encoded data. Using the [#Object Container File] | ||
| //! this is directly possible in Avro. Avro supports various compression codecs: | ||
| //! | ||
| //! - deflate | ||
| //! - bzip2 | ||
| //! - Snappy | ||
| //! - XZ | ||
| //! - Zstandard | ||
| //! | ||
| //! All readers are required to implement the `deflate` codec, but most implementations implement most | ||
| //! codecs. | ||
| //! |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check the file at the specified lines
cat -n avro/src/documentation/primer.rs | sed -n '55,105p'Repository: martin-augment/avro-rs
Length of output: 3368
🏁 Script executed:
# Search for other uses of ++version++ in the codebase
rg '\+\+version\+\+' --type rustRepository: martin-augment/avro-rs
Length of output: 895
🏁 Script executed:
# Check if there are other documentation references to understand versioning patterns
rg 'avro\.apache\.org/docs' --type rust -A 2 -B 2Repository: martin-augment/avro-rs
Length of output: 11356
Replace placeholder spec links, fix intra-doc link syntax, and correct grammar.
The ++version++ placeholder won't resolve in rustdoc. The [#Object Container File] syntax is invalid for intra-doc links and should use lowercase with hyphens. There's also a grammar error on line 87.
Proposed fixes
-//! [the schema section of the specification]: https://avro.apache.org/docs/++version++/specification/#schema-declaration
+//! [the schema section of the specification]: https://avro.apache.org/docs/1.12.0/specification/#schema-declaration
@@
-//! #### [Object Container File](https://avro.apache.org/docs/++version++/specification/#object-container-files)
+//! #### [Object Container File](https://avro.apache.org/docs/1.12.0/specification/#object-container-files)
@@
-//! #### [Single Object Encoding](https://avro.apache.org/docs/++version++/specification/#single-object-encoding)
+//! #### [Single Object Encoding](https://avro.apache.org/docs/1.12.0/specification/#single-object-encoding)
@@
-//! #### [Avro JSON](https://avro.apache.org/docs/++version++/specification/#json-encoding)
+//! #### [Avro JSON](https://avro.apache.org/docs/1.12.0/specification/#json-encoding)
@@
-//! Not be confused with the schema definition which is also in JSON. This is the Avro data encoded
+//! Not to be confused with the schema definition which is also in JSON. This is the Avro data encoded
@@
-//! For records with low entropy it can be useful to compress the encoded data. Using the [`#Object` Container File]
+//! For records with low entropy it can be useful to compress the encoded data. Using the [Object Container File](`#object-container-file`)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| //! [the schema section of the specification]: https://avro.apache.org/docs/++version++/specification/#schema-declaration | |
| //! | |
| //! ## Data serialization and deserialization | |
| //! There are various formats to encode and decode Avro data. Most formats use the Avro binary encoding. | |
| //! | |
| //! #### [Object Container File](https://avro.apache.org/docs/++version++/specification/#object-container-files) | |
| //! This is the most common file format used for Avro, it uses the binary encoding. It includes the | |
| //! schema in the file, and can therefore be decoded by a reader who doesn't have the schema. It includes | |
| //! many records in one file. | |
| //! | |
| //! This file format can be used via the [`Reader`](crate::Reader) and [`Writer`](crate::Writer) types. | |
| //! | |
| //! #### [Single Object Encoding](https://avro.apache.org/docs/++version++/specification/#single-object-encoding) | |
| //! This file format also uses the binary encoding, but the schema is not included directly. It instead | |
| //! includes a fingerprint of the schema, which a reader can look up in a schema database or compare | |
| //! with the fingerprint that the reader is expecting. This file format always contains one record. | |
| //! | |
| //! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader), | |
| //! [`GenericSingleObjectWriter`](crate::GenericSingleObjectReader), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader), | |
| //! and [`SpecificSingleObjectWriter`](crate::SpecificSingleObjectWriter) types. | |
| //! | |
| //! #### Avro datums | |
| //! This is not really a file format, as it's just the raw Avro binary data. It does not include a | |
| //! schema and can therefore not be decoded without the reader knowing **exactly** which schema was | |
| //! used to write it. | |
| //! | |
| //! This file format can be used via the [`to_avro_datum`](crate::to_avro_datum), [`from_avro_datum`](crate::from_avro_datum), | |
| //! [`to_avro_datum_schemata`](crate::to_avro_datum_schemata), [`from_avro_datum_schemata`](crate::from_avro_datum_schemata), | |
| //! [`from_avro_datum_reader_schemata`](crate::from_avro_datum_reader_schemata), and | |
| //! [`write_avro_datum_ref`](crate::write_avro_datum_ref) functions. | |
| //! | |
| //! #### [Avro JSON](https://avro.apache.org/docs/++version++/specification/#json-encoding) | |
| //! Not be confused with the schema definition which is also in JSON. This is the Avro data encoded | |
| //! in JSON. | |
| //! | |
| //! It can be used via the [`From<serde_json::Value> for Value`](crate::types::Value) and | |
| //! [`TryFrom<Value> for serde_json::Value`](crate::types::Value) implementations. | |
| //! | |
| //! ## Compression | |
| //! For records with low entropy it can be useful to compress the encoded data. Using the [#Object Container File] | |
| //! this is directly possible in Avro. Avro supports various compression codecs: | |
| //! | |
| //! - deflate | |
| //! - bzip2 | |
| //! - Snappy | |
| //! - XZ | |
| //! - Zstandard | |
| //! | |
| //! All readers are required to implement the `deflate` codec, but most implementations implement most | |
| //! codecs. | |
| //! | |
| //! [the schema section of the specification]: https://avro.apache.org/docs/1.12.0/specification/#schema-declaration | |
| //! | |
| //! ## Data serialization and deserialization | |
| //! There are various formats to encode and decode Avro data. Most formats use the Avro binary encoding. | |
| //! | |
| //! #### [Object Container File](https://avro.apache.org/docs/1.12.0/specification/#object-container-files) | |
| //! This is the most common file format used for Avro, it uses the binary encoding. It includes the | |
| //! schema in the file, and can therefore be decoded by a reader who doesn't have the schema. It includes | |
| //! many records in one file. | |
| //! | |
| //! This file format can be used via the [`Reader`](crate::Reader) and [`Writer`](crate::Writer) types. | |
| //! | |
| //! #### [Single Object Encoding](https://avro.apache.org/docs/1.12.0/specification/#single-object-encoding) | |
| //! This file format also uses the binary encoding, but the schema is not included directly. It instead | |
| //! includes a fingerprint of the schema, which a reader can look up in a schema database or compare | |
| //! with the fingerprint that the reader is expecting. This file format always contains one record. | |
| //! | |
| //! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader), | |
| //! [`GenericSingleObjectWriter`](crate::GenericSingleObjectReader), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader), | |
| //! and [`SpecificSingleObjectWriter`](crate::SpecificSingleObjectWriter) types. | |
| //! | |
| //! #### Avro datums | |
| //! This is not really a file format, as it's just the raw Avro binary data. It does not include a | |
| //! schema and can therefore not be decoded without the reader knowing **exactly** which schema was | |
| //! used to write it. | |
| //! | |
| //! This file format can be used via the [`to_avro_datum`](crate::to_avro_datum), [`from_avro_datum`](crate::from_avro_datum), | |
| //! [`to_avro_datum_schemata`](crate::to_avro_datum_schemata), [`from_avro_datum_schemata`](crate::from_avro_datum_schemata), | |
| //! [`from_avro_datum_reader_schemata`](crate::from_avro_datum_reader_schemata), and | |
| //! [`write_avro_datum_ref`](crate::write_avro_datum_ref) functions. | |
| //! | |
| //! #### [Avro JSON](https://avro.apache.org/docs/1.12.0/specification/#json-encoding) | |
| //! Not to be confused with the schema definition which is also in JSON. This is the Avro data encoded | |
| //! in JSON. | |
| //! | |
| //! It can be used via the [`From<serde_json::Value> for Value`](crate::types::Value) and | |
| //! [`TryFrom<Value> for serde_json::Value`](crate::types::Value) implementations. | |
| //! | |
| //! ## Compression | |
| //! For records with low entropy it can be useful to compress the encoded data. Using the [Object Container File](`#object-container-file`) | |
| //! this is directly possible in Avro. Avro supports various compression codecs: | |
| //! | |
| //! - deflate | |
| //! - bzip2 | |
| //! - Snappy | |
| //! - XZ | |
| //! - Zstandard | |
| //! | |
| //! All readers are required to implement the `deflate` codec, but most implementations implement most | |
| //! codecs. | |
| //! |
🤖 Prompt for AI Agents
In `@avro/src/documentation/primer.rs` around lines 55 - 105, Replace all
occurrences of the literal "++version++" in the spec URLs with a resolvable spec
path (e.g. "current" or the actual spec version) so the links render in rustdoc;
change the invalid intra-doc link label "[`#Object` Container File]" to a proper
reference-style anchor (e.g. "object-container-files" or the lowercase-hyphen
form used by rustdoc) wherever the Object Container File section is referenced;
and fix the grammar in the Avro JSON paragraph by changing "Not be confused with
the schema definition which is also in JSON." to a proper sentence (e.g. "Do not
be confused with the schema definition, which is also in JSON."). Use the
surrounding symbols to find locations: the spec URLs, the "[`#Object` Container
File]" reference, and the "Avro JSON" paragraph that mentions
From<serde_json::Value> for Value and TryFrom<Value> for serde_json::Value.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The CodeRabbit AI reviewer is partially correct! The ++version++ will work anywhere. The intra-link to Object Container File should be fixed though! Prevents having a broken link in the documentation
| //! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader), | ||
| //! [`GenericSingleObjectWriter`](crate::GenericSingleObjectReader), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader), | ||
| //! and [`SpecificSingleObjectWriter`](crate::SpecificSingleObjectWriter) types. |
There was a problem hiding this comment.
Fix the Single Object Encoding writer link.
GenericSingleObjectWriter currently links to the reader type, which is misleading in the rendered docs.
Proposed fix
-//! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader),
-//! [`GenericSingleObjectWriter`](crate::GenericSingleObjectReader), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader),
+//! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader),
+//! [`GenericSingleObjectWriter`](crate::GenericSingleObjectWriter), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader),📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| //! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader), | |
| //! [`GenericSingleObjectWriter`](crate::GenericSingleObjectReader), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader), | |
| //! and [`SpecificSingleObjectWriter`](crate::SpecificSingleObjectWriter) types. | |
| //! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader), | |
| //! [`GenericSingleObjectWriter`](crate::GenericSingleObjectWriter), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader), | |
| //! and [`SpecificSingleObjectWriter`](crate::SpecificSingleObjectWriter) types. |
🤖 Prompt for AI Agents
In `@avro/src/documentation/primer.rs` around lines 72 - 74, The doc comment
incorrectly links GenericSingleObjectWriter to the reader type; update the
documentation line to reference the correct writer type path (replace
[`GenericSingleObjectWriter`](crate::GenericSingleObjectReader) with
[`GenericSingleObjectWriter`](crate::GenericSingleObjectWriter)) so the rendered
docs point to the writer, and verify the other three links
(`SpecificSingleObjectReader`, `SpecificSingleObjectWriter`, and
`GenericSingleObjectReader`) remain correct.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The CodeRabbit AI reviewer is correct! There is a wrong link to a different type. Prevents having a link to a type different than the intended one.
| String, | ||
| /// A `array` Avro schema. Avro arrays are required to have the same type for each element. | ||
| /// This variant holds the `Schema` for the array element type. | ||
| /// A `array` Avro schema. |
There was a problem hiding this comment.
Grammar issue: "A array" should be "An array".
The article should be "An" before a word starting with a vowel sound.
📝 Proposed fix
- /// A `array` Avro schema.
+ /// An `array` Avro schema.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /// A `array` Avro schema. | |
| /// An `array` Avro schema. |
🤖 Prompt for AI Agents
In `@avro/src/schema/mod.rs` at line 110, Update the doc comment that currently
reads "A `array` Avro schema." to use the correct indefinite article by changing
it to "An `array` Avro schema." — locate the docstring attached to the Avro
array schema (the comment adjacent to the Array variant/struct in mod.rs) and
replace "A `array`" with "An `array`".
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The CodeRabbit AI reviewer is correct! There is a minor grammar error that needs to be fixed. Prevents having a wrong English grammar.
| /// Parses a valid Avro schema into [the Parsing Canonical Form]. | ||
| /// | ||
| /// [the Parsing Canonical From](https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas) |
There was a problem hiding this comment.
Typo: "Canonical From" should be "Canonical Form".
The link reference on line 943 has a typo that also breaks the doc link pattern (line 941 references [the Parsing Canonical Form] but line 943 defines [the Parsing Canonical From]).
📝 Proposed fix
/// Parses a valid Avro schema into [the Parsing Canonical Form].
///
-/// [the Parsing Canonical From](https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas)
+/// [the Parsing Canonical Form](https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /// Parses a valid Avro schema into [the Parsing Canonical Form]. | |
| /// | |
| /// [the Parsing Canonical From](https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas) | |
| /// Parses a valid Avro schema into [the Parsing Canonical Form]. | |
| /// | |
| /// [the Parsing Canonical Form](https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas) |
🤖 Prompt for AI Agents
In `@avro/src/schema/mod.rs` around lines 941 - 943, Fix the typo in the module
doc comment: change the link label "[the Parsing Canonical From]" to "[the
Parsing Canonical Form]" so it matches the earlier reference "[the Parsing
Canonical Form]" and restores the doc link. Locate the comment block in
avro/src/schema/mod.rs that documents parsing (the doc lines containing "[the
Parsing Canonical Form]") and update the spelled word "From" to "Form" in the
link definition.
There was a problem hiding this comment.
value:good-to-have; category:typo; feedback: The CodeRabbit AI reviewer is correct! There is a small typo that needs to be fixed. Prevents using a wrong word in the documentation.
| /// Create an array of `Schema`'s from an iterator of JSON Avro schemas. | ||
| /// | ||
| /// It is allowed that the schemas have cross-dependencies; these will be resolved during parsing. |
There was a problem hiding this comment.
Minor grammar issue: "Schema`'s" → "Schemas"
The doc comment uses possessive form where plural is intended.
- /// Create an array of `Schema`'s from an iterator of JSON Avro schemas.
+ /// Create an array of `Schema`s from an iterator of JSON Avro schemas.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /// Create an array of `Schema`'s from an iterator of JSON Avro schemas. | |
| /// | |
| /// It is allowed that the schemas have cross-dependencies; these will be resolved during parsing. | |
| /// Create an array of `Schema`s from an iterator of JSON Avro schemas. | |
| /// | |
| /// It is allowed that the schemas have cross-dependencies; these will be resolved during parsing. |
🤖 Prompt for AI Agents
In `@avro/src/schema/parser.rs` around lines 68 - 70, Update the doc comment in
avro/src/schema/parser.rs that currently reads "Create an array of `Schema`'s
from an iterator of JSON Avro schemas." to use the correct plural form "Schemas"
(e.g., "Create an array of Schemas from an iterator of JSON Avro schemas.").
Locate the doc comment above the parser functionality that documents creating an
array of Schema values and replace the possessive "Schema`'s" with the plain
plural "Schemas" so the comment reads grammatically correct.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The CodeRabbit AI reviewer is correct! There is a grammar issue that needs to be fixed. Prevents having a wrong grammar in the documentation.
|
|
||
| /// Parse a `serde_json::Value` representing a Avro record type into a | ||
| /// `Schema`. | ||
| /// Parse a `serde_json::Value` representing a Avro record type into a `Schema`. |
There was a problem hiding this comment.
Grammar: "a Avro" → "an Avro"
Multiple doc comments use "a Avro" instead of "an Avro". The word "Avro" starts with a vowel sound.
📝 Suggested fixes across this file
- /// Parse a `serde_json::Value` representing a Avro record type into a `Schema`.
+ /// Parse a `serde_json::Value` representing an Avro record type into a `Schema`.Line 617:
- /// Parse a `serde_json::Value` representing a Avro enum type into a `Schema`.
+ /// Parse a `serde_json::Value` representing an Avro enum type into a `Schema`.Line 694:
- /// Parse a `serde_json::Value` representing a Avro array type into a `Schema`.
+ /// Parse a `serde_json::Value` representing an Avro array type into a `Schema`.Line 712:
- /// Parse a `serde_json::Value` representing a Avro map type into a `Schema`.
+ /// Parse a `serde_json::Value` representing an Avro map type into a `Schema`.Line 730:
- /// Parse a `serde_json::Value` representing a Avro union type into a `Schema`.
+ /// Parse a `serde_json::Value` representing an Avro union type into a `Schema`.Line 758:
- /// Parse a `serde_json::Value` representing a Avro fixed type into a `Schema`.
+ /// Parse a `serde_json::Value` representing an Avro fixed type into a `Schema`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /// Parse a `serde_json::Value` representing a Avro record type into a `Schema`. | |
| /// Parse a `serde_json::Value` representing an Avro record type into a `Schema`. |
🤖 Prompt for AI Agents
In `@avro/src/schema/parser.rs` at line 538, Several doc comments in parser.rs use
the incorrect article "a Avro"; change those occurrences to "an Avro". Edit the
doc comment that currently reads "Parse a `serde_json::Value` representing a
Avro record type into a `Schema`" (the comment above the function that parses a
serde_json::Value into a Schema) and the other doc comments flagged (around the
parser functions that describe parsing Avro types such as record/union/named
types) to use "an Avro" instead of "a Avro".
There was a problem hiding this comment.
value:good-to-have; category:typo; feedback: The CodeRabbit AI reviewer is correct! There is a minor typo that needs to be fixed.
| //! // don't parse any schema before registering the custom validator(s)! | ||
| //! | ||
| //! set_schema_name_validator(Box::new(MyCustomValidator)); | ||
| //! | ||
| //! // ... use the library | ||
| //! ``` |
There was a problem hiding this comment.
Example ignores Result from set_schema_name_validator
The example doesn't handle the Result returned by set_schema_name_validator, which will produce an #[must_use] warning for users following this documentation.
📝 Suggested fix
//! // don't parse any schema before registering the custom validator(s)!
//!
-//! set_schema_name_validator(Box::new(MyCustomValidator));
+//! set_schema_name_validator(Box::new(MyCustomValidator)).ok();
//!
//! // ... use the libraryAlternatively, show proper error handling:
//! if set_schema_name_validator(Box::new(MyCustomValidator)).is_err() {
//! // A validator was already registered
//! }
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| //! // don't parse any schema before registering the custom validator(s)! | |
| //! | |
| //! set_schema_name_validator(Box::new(MyCustomValidator)); | |
| //! | |
| //! // ... use the library | |
| //! ``` | |
| //! // don't parse any schema before registering the custom validator(s)! | |
| //! | |
| //! set_schema_name_validator(Box::new(MyCustomValidator)).ok(); | |
| //! | |
| //! // ... use the library | |
| //! |
🤖 Prompt for AI Agents
In `@avro/src/validator.rs` around lines 38 - 43, Update the documentation example
so it does not ignore the Result returned by set_schema_name_validator; locate
the example around set_schema_name_validator(Box::new(MyCustomValidator)) and
change it to handle the Result (for example by checking is_err() and handling
the "validator already registered" case or propagating the error) so users
following the docs won't hit an #[must_use] warning.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The CodeRabbit AI reviewer is correct! The code example promotes bad practices by ignoring the Result. A user copying this example in the his/her application will face an issue when an Err is returned because it won't be handled. Prevents promoting bad coding practices.
🤖 Augment PR SummarySummary: This PR reworks the crate’s documentation to make it more modular and rustdoc-friendly. Changes:
Technical Notes: The new documentation is intended to be built via rustdoc (docs.rs builds with all features) and aims to reduce duplication between README and crate-level docs while improving discoverability via module docs. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
|
|
||
| #[error("Unable to allocate {desired} bytes (maximum allowed: {maximum})")] | ||
| #[error( | ||
| "Unable to allocate {desired} bytes (maximum allowed: {maximum}). Change the limit using `utils::max_allocation_bytes`" |
There was a problem hiding this comment.
The error message suggests calling utils::max_allocation_bytes, but the API is util::max_allocation_bytes (and the crate-root max_allocation_bytes is deprecated), so this guidance currently points to a non-existent path.
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The Augment AI reviewer is correct! The module name used in the error message is wrong and it won't work if a developer copy/pastes it into his/her application. Prevents suggesting a solution which won't work.
| /// https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas | ||
| /// Parses a valid Avro schema into [the Parsing Canonical Form]. | ||
| /// | ||
| /// [the Parsing Canonical From](https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas) |
There was a problem hiding this comment.
The link text above uses [the Parsing Canonical Form], but the reference label here is From, so this will render as an unresolved reference link (and likely trigger clippy::doc_markdown).
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:good-to-have; category:typo; feedback: The Augment AI reviewer is correct! There is a typo in one of the words that changes completely the meaning of the sentence. Prevents releasing documentation with confusing meaning.
| //! | ||
| //! Schemas are represented using the [`Schema`](crate::Schema) type. | ||
| //! | ||
| //! [the schema section of the specification]: https://avro.apache.org/docs/++version++/specification/#schema-declaration |
There was a problem hiding this comment.
These Avro spec URLs use the literal ++version++ placeholder, which won’t resolve on avro.apache.org and will produce dead links in rendered docs.
Other Locations
avro/src/documentation/primer.rs:60avro/src/documentation/primer.rs:67avro/src/documentation/primer.rs:86avro/src/schema_compatibility.rs:22avro/src/schema/mod.rs:86
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:annoying; category:bug; feedback: The Augment AI reviewer is not correct! The ++version++ is a special version placeholder meaning "next version". It does resolve correctly and there are no issues with it.
| //! with the fingerprint that the reader is expecting. This file format always contains one record. | ||
| //! | ||
| //! This file format can be used via the [`GenericSingleObjectReader`](crate::GenericSingleObjectReader), | ||
| //! [`GenericSingleObjectWriter`](crate::GenericSingleObjectReader), [`SpecificSingleObjectReader`](crate::SpecificSingleObjectReader), |
There was a problem hiding this comment.
GenericSingleObjectWriter is linked to crate::GenericSingleObjectReader here, so the docs will take users to the wrong type.
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The Augment AI reviewer is correct! The link for the Writer type points to the Reader type. Prevents navigating to the wrong type when wanting to read the GenericSingleObjectWriter's documentation
| //! [`TryFrom<Value> for serde_json::Value`](crate::types::Value) implementations. | ||
| //! | ||
| //! ## Compression | ||
| //! For records with low entropy it can be useful to compress the encoded data. Using the [#Object Container File] |
There was a problem hiding this comment.
[#Object Container File] is an undefined reference-style link (no target is defined), so this will render as a broken link and may trigger clippy::doc_markdown.
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The Augment AI reviewer is correct! The intra-link uses a wrong format and thus it won't render as a proper link to the wanted target. Prevents releasing documentation with broken links
| /// 1. In combination with `#[serde(with = "path::to::module)]` | ||
| /// | ||
| /// To get the schema, it will call the functions `fn get_schema_in_ctxt(&mut Names, &Namespace) -> Schema` | ||
| /// and `fn get_record_fields_in_ctxt(&mut Names, &Namespace) -> Schema` in the module provided |
There was a problem hiding this comment.
This section says get_record_fields_in_ctxt returns Schema, but AvroSchemaComponent::get_record_fields_in_ctxt actually takes a first_field_position: usize and returns Option<Vec<RecordField>>, so the guidance for #[avro(with)] modules looks incorrect.
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The Augment AI reviewer is correct! The get_record_fields_in_ctxt () function arguments and return type are copy/pasted from get_schema_in_ctxt() and are wrong. Prevents releasing documentation with wrong content.
| //! | ||
| //! 2. Incompatible schemas (`Err`) | ||
| //! | ||
| //! For example, a long can never be resolved to a long: |
There was a problem hiding this comment.
The text says “a long can never be resolved to a long”, but the example is long -> int; the wording looks incorrect/misleading.
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:useful; category:documentation; feedback: The Augment AI reviewer is correct! There is a typo in the second usage of "long" - it should be an "int" schema. Prevents releasing documentation that is wrong and misleading.
| //! writer.append_ser(&foo)?; | ||
| //! | ||
| //! // Always flush | ||
| //! writer.flush(); |
There was a problem hiding this comment.
This example ignores the AvroResult returned by Writer::flush(), which can hide I/O/codec errors and will likely produce an unused_must_use warning for users copying it.
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The Augment AI reviewer is correct! The documentation promotes bad practice of ignoring the result of a method invocation. A developer copying this example may miss an eventual error result of the flush operation
|
|
||
| //! This crate provides the `AvroSchema` derive macro. | ||
| //! ```no_run | ||
| //! #[derive(AvroSchema)] |
There was a problem hiding this comment.
This no_run snippet derives AvroSchema without bringing the derive macro into scope, which can make the doctest fail to compile depending on rustdoc’s injected imports.
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The Augment AI reviewer is correct! Since there is no "imports" section it is not clear where AvroSchema type comes from. It would be better to use a fully qualified type name - apache_avro::AvroSchema.
| //! ``` | ||
| //! Please see the documentation of the [`AvroSchema`] trait for instructions on how to use it. | ||
| //! | ||
| //! [`AvroSchema`]: https://docs.rs/apache-avro/latest/apache_avro/schema/trait.AvroSchema.html |
There was a problem hiding this comment.
The AvroSchema trait link points to apache_avro/schema/trait.AvroSchema.html, but the trait is under apache_avro::serde (and re-exported at the crate root), so this URL likely 404s.
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
value:good-to-have; category:documentation; feedback: The Augment AI reviewer is correct! The AvroSchema type has been moved recently to the "serde" module and this link now is broken and has to be updated.
value:good-to-have; category:documentation; feedback: The Claude AI reviewer is correct! There is a copy/paste error that needs to be fixed. Prevents having a wrong link in the documentation. |
value:good-to-have; category:documentation; feedback: The CodeRabbit AI reviewer is correct! There is a small grammar error that needs to be fixed. Prevents using wrong English in the documentation |
2 participants
451: To review by AI