Serial-ATA/lofty-rs

Better document existing utility methods

Open

#357 opened on Mar 12, 2024

View on GitHub
 (1 comment) (1 reaction) (0 assignees)Rust (72 forks)auto 404
docsgood first issuehelp wanted

Repository metrics

Stars
 (342 stars)
PR merge metrics
 (PR metrics pending)

Description

Having looked through multiple projects over the years, it's clear that Lofty's API either isn't the best documented or the easiest to understand. Some patterns keep showing up, namely:

  • Not using {Tag::take_strings, Tag::get_strings}
    • Many projects could use take_strings instead of repeatedly cloning, since most don't write tags back to files.
    • Additionally, many projects could benefit from not having to iterate TagItems and check the ItemValue. get_strings exists for that purpose.
    • Finally, I have seen some projects that don't know about ItemKey. That makes it appear as though Lofty is only capable of providing the items accessible through Accessor. (!!!)
  • Not using Tag::get_picture_type
    • Many will iterate all pictures to find the one they want. That isn't necessary.

I consider this an issue with the docs, not with the projects. I believe there are other things I have found in the past, but this is what I could think of for now.

Contributor guide

Research direction
Explore the Lofty documentation and identify sections where utility methods like Tag::take strings, Tag::get strings, ItemKey, and Tag::get picture type are underused or not prominent. Add examples and cross references to improve discoverability.
Tech stack
rust
Domain
backend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Rust
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75