Improve documentation with fixes, comments, and examples#636
Open
thedavidweng wants to merge 9 commits intoSerial-ATA:mainfrom
Open
Improve documentation with fixes, comments, and examples#636thedavidweng wants to merge 9 commits intoSerial-ATA:mainfrom
thedavidweng wants to merge 9 commits intoSerial-ATA:mainfrom
Conversation
- Fix "an feature" -> "a feature" in doc/ISSUES.md - Fix "bugs reports" -> "bug reports" in doc/PULL_REQUESTS.md - Fix broken src/file.rs path -> lofty/src/file/file_type.rs in doc/NEW_FILE.md - Update fuzz example imports to match actual fuzz targets in doc/NEW_FILE.md - Fix missing &mut self on remove_artist() in doc/NEW_TAG.md - Fix remove() method signature (wrong return type) in doc/NEW_TAG.md - Fix broken ../src/ paths to ../lofty/src/ in doc/NEW_TAG.md - Fix "This is only gets" -> "This only gets" in lofty/src/tag/item.rs
…nums Remove #[allow(missing_docs)] from: - FileType enum variants in file/file_type.rs - MpegVersion, Layer, ChannelMode, Emphasis in mpeg/header.rs - WavFormat in iff/wav/properties.rs - PictureType in picture.rs - Mp4Codec and AudioObjectType in mp4/properties.rs All public enum variants now have descriptive doc comments.
Remove #[allow(missing_docs)] from: - ChannelType in relative_volume_adjustment_frame.rs - EventType in event_timing_codes_frame.rs - SyncTextContentType in sync_text.rs
Remove #[allow(missing_docs)] from: - FrameHeader in id3/v2/frame/header/mod.rs - TimestampFrame in id3/v2/items/timestamp_frame.rs - Timestamp in tag/items/timestamp.rs - ReplayGain and EncoderInfo in musepack/sv8/properties.rs - SplitTagRemainder in tag/mod.rs
Add one-line doc comments to ~88 previously undocumented ItemKey variants while preserving the existing detailed documentation on variants like AlbumArtists, Popularimeter, RecordingDate, Lyrics, etc.
Remove #[allow(missing_docs)] from the define_channels! macro and add descriptive doc comments to all 18 channel mask constants.
All variants are now documented, so the allow attribute is no longer needed.
Add # Examples sections with doc-tested code for: - Timestamp: parsing via FromStr and formatting via Display - TagItem: construction with TagItem::new
Add //! doc comments to: - ape/tag/mod.rs: describe APEv2 tags - id3/v2/tag.rs: describe ID3v2 tags and versions Expand //! doc comments in: - iff/mod.rs: describe IFF container format - id3/mod.rs: mention ID3v1 and ID3v2 submodules
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Typos & stale references:
Fixed grammar in doc/ISSUES.md and doc/PULL_REQUESTS.md
Fixed broken file path references in doc/NEW_FILE.md and doc/NEW_TAG.md (6 stale ../src/ paths → ../lofty/src/)
Fixed code example bugs in doc/NEW_TAG.md (missing &mut self, wrong return type)
Updated fuzz example imports in doc/NEW_FILE.md
Fixed typo in lofty/src/tag/item.rs
Removed ALL #[allow(missing_docs)] (previously 15+ files):
Added doc comments to ~200 items across: FileType, MpegVersion, Layer, ChannelMode, Emphasis, WavFormat, PictureType, Mp4Codec, AudioObjectType, ChannelType, EventType, SyncTextContentType, FrameHeader, TimestampFrame, Timestamp, ReplayGain, EncoderInfo, SplitTagRemainder, ItemKey (~88 variants), ChannelMask (18 constants)
Examples:
Added doc-tested examples to Timestamp and TagItem structs
Module docs:
Added/improved //! module docs for ape/tag, id3/v2/tag, iff, id3