Add module-level documentation to lib.rs #545
Conversation
Added comprehensive module-level documentation to cargo-test-fuzz/src/lib.rs explaining the crate's purpose, functionality, and how it integrates with the test-fuzz project.
|
|
|
@smoelius please check if the documentation I added is to your liking, if you think its good then please merge it. Thank you. |
|
hey @smoelius could you please approve the ci tests? |
|
@smoelius I think this can be merged now. |
cargo-test-fuzz/src/lib.rs
Outdated
| //! The primary features of this crate include: | ||
| //! | ||
| //! - Building and running fuzz tests using `afl.rs` | ||
| //! - Managing and generating fuzzing corpora | ||
| //! - Displaying and replaying crashes and hangs | ||
| //! - Consolidating and resetting test output | ||
| //! | ||
| //! This crate provides the backend for the `cargo test-fuzz` subcommand, which allows users to: | ||
| //! - Run fuzzing operations against test targets annotated with the `test_fuzz` macro | ||
| //! - Manage fuzzing artifacts (corpus, crashes, hangs) | ||
| //! - Configure fuzzing parameters (timeout, CPU usage, etc.) |
There was a problem hiding this comment.
I think the number of users that use cargo-test-fuzz as a library is small, and maybe even zero.
Such users are likely to already know what cargo-test-fuzz is. So I doubt this text would be helpful to them.
To be honest, I think this text can be eliminated.
Ideally, it would be replaced with a reference to run since that is the library's main export:
test-fuzz/cargo-test-fuzz/src/lib.rs
Line 133 in b31d304
But I would understand if you don't want to go to that trouble.
EDIT: Just as a followup, #543 mentioned these things:
Object enum, TestFuzz struct, run function
I think there would be value in addressing those in the documentation. If someone were to use this crate as a library, those would be the things that they use.
Please forgive me for asking, but was this generated with an LLM?
There was a problem hiding this comment.
@smoelius About the initial documentation - I had GitHub Copilot enabled and after writing the first couple of lines, it suggested the rest of the content. Since it was a simple documentation fix and the suggestions looked reasonable, I went with it after reviewing.
I've changed the documentation so that it is focused on documenting the primary exports as you mentioned. I wrote this version myself without relying on Copilot's suggestions, hope this won't cause any problems.
There was a problem hiding this comment.
@smoelius About the initial documentation - I had GitHub Copilot enabled and after writing the first couple of lines, it suggested the rest of the content. Since it was a simple documentation fix and the suggestions looked reasonable, I went with it after reviewing.
Wow. I was not aware Copliot did that. Thank you for explaining.
I've changed the documentation so that it is focused on documenting the primary exports as you mentioned. I wrote this version myself without relying on Copilot's suggestions, hope this won't cause any problems.
What you have now is a definite improvement to the code. Thank you!
While you're here, would you mind adding #[doc(hidden)] to run_without_exit_code? Your changes caused me to realize that function should not be public. I would prefer to not remove the pub now since that would be a breaking change, but we could at least hide the function.
There was a problem hiding this comment.
@smoelius I've added the #[doc(hidden)] to run_without_exit_code as you requested, please check if I have to make any more changes.
Updated the documentation for the cargo-test-fuzz crate to clarify its purpose and functionality.
|
The CI failure is not your PR's fault. I'll fix it. |
Introduced a hidden doc comment for the run_without_exit_code function in lib.rs to improve code clarity without exposing it in the public API.
|
@smoelius could you approve the ci test? or are you working to fix the test rn? |
Sorry for the delay. The CI failure should be fixed now. |
|
@smoelius the ci tests have passes, can this be merged now? |
|
Thanks, @markv44! |
Description
This PR addresses issue #543 by adding comprehensive module-level documentation to the main library file
cargo-test-fuzz/src/lib.rs. The documentation provides an overview of the crate's purpose, its primary features, and how it integrates with the largertest-fuzzproject.Changes
//!doc comments at the beginning of the filecargo test-fuzzsubcommandRelated Issue
Closes #543
Checklist