8000 doc: massive overhaul of documentation by phip1611 · Pull Request #1264 · rust-osdev/uefi-rs · GitHub
[go: up one dir, main page]
Skip to content

doc: massive overhaul of documentation #1264

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 13 commits into from
Closed

doc: massive overhaul of documentation #1264

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
79c048a
uefi: remove documentation about already removed feature
phip1611 Jul 28, 2024
676c585
doc: unified new TL;DR/description entry
phip1611 Jul 30, 2024
27ec946
doc: add "About this Document"
phip1611 Jul 30, 2024
d85b4c9
doc: move background info to lib.rs
phip1611 Jul 30, 2024
9f9e5ca
doc: streamline sections Contributing, MSRV, and License
phip1611 Jul 30, 2024
505e70f
doc: add "About" section
phip1611 Jul 30, 2024
e46e74a
doc: extend About section with Example Use Cases
phip1611 Jul 30, 2024
02bc2cf
doc: add Supported Architectures
phip1611 Jul 30, 2024
52954f4
doc: add "Comparison to other Projects in the Ecosystem"
phip1611 Jul 30, 2024
837fe5c
doc: add "API/User Documentation, Documentation Structure, and other …
phip1611 Jul 30, 2024
b9829d7
doc: Crate organization -> Library Structure & Tips
phip1611 Jul 30, 2024
e0fde84
doc: reorder links alphabetically in lib.rs
phip1611 Jul 30, 2024
5c9343f
doc: final streamlining of README files
phip1611 Jul 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
doc: streamline sections Contributing, MSRV, and License 
Copy MSRV, License, and Contributing sections to lib.rs and streamline it
with the README equivalents. We should also include these information in
lib.rs, as it is the main entry point into everything relevant about the
library. At least, it should from now on.

The big benefit is that the documentation on `docs.rs` then covers
everything relevant.
  • Loading branch information
@phip1611
phip1611 committed Jul 30, 2024
commit 9f9e5ca21ab529cab463282a8d72ab3707404cb0
12 changes: 8 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,11 +122,14 @@ most of the library's functionality.
Check out the testing project's [`README.md`](uefi-test-runner/README.md) for
prerequisites for running the tests.

## Contributing
## Discuss and Contribute

We welcome issues and pull requests! For instructions on how to set up a
development environment and how to add new protocols, check out
[CONTRIBUTING.md](CONTRIBUTING.md).
For general discussions, feel free to join us in our [Zulip] and ask
your questions there.

Further, you can submit bugs and also ask questions in our [issue tracker].
Contributions in form of a PR are also highly welcome. Check our
[contributing guide](./CONTRIBUTING.md) for details.

## License

Expand All @@ -137,3 +140,4 @@ modifications to the files must be open-sourced.
The full text of the license is available in the [license file](LICENSE).

[UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface
[Zulip]: https://rust-osdev.zulipchat.com
29 changes: 26 additions & 3 deletions uefi/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,6 @@
//! important UEFI concepts. For more details of UEFI, see the latest [UEFI
//! Specification][spec].
//!
//! Feel free to file bug reports and questions in our [issue tracker], and [PR
//! contributions][contributing] are also welcome!
//!
//! # About this Document
8000
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO this section isn't needed. Having some description at the front of a multi-page document can be helpful, but here it's pretty clear what all the content is by just scanning through the following sections on the page.

//!
//! In this document, you find general information about this crate, such
Expand Down Expand Up @@ -83,6 +80,30 @@
//! only unfold their potential when you invoke `uefi::helpers::init` as soon
//! as possible in your application.
//!
//! # Discuss and Contribute
//!
//! For general discussions, feel free to join us in our [Zulip] and ask
//! your questions there.
//!
//! Further, you can submit bugs and also ask questions in our [issue tracker].
//! Contributions in form of a PR are also highly welcome. Check our
//! [contributing guide][contributing] for details.
//!
//! # MSRV
//! <!-- Keep in Sync with README! -->
//!
//! The minimum supported Rust version is currently 1.70.
//! Our policy is to support at least the past two stable releases.
//!
//! # License
//! <!-- Keep in Sync with README! -->
//!
//! The code in this repository is licensed under the Mozilla Public License 2.
//! This license allows you to use the crate in proprietary programs, but any
//! modifications to the files must be open-sourced.
//!
//! The full text of the license is available in the [license file][LICENSE].
//!
//! # Trivia and Background
//!
//! [UEFI] started as the successor firmware to the BIOS in x86 space and
Expand All @@ -94,8 +115,10 @@
//! form of additional drivers, OS-specific bootloaders, or any different kind
//! of low-level applications (such as an [IRC client][uefirc]).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The IRC client is a neat project, but I'm not sure it makes sense to mention in the readme since it's a pretty niche use case, unlike drivers and bootloaders.

//!
//! [LICENSE]: https://github.com/rust-osdev/uefi-rs/blob/main/uefi/LICENSE
//! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/
//! [UEFI]: https://uefi.org/
//! [Zulip]: https://rust-osdev.zulipchat.com
//! [`BootServices`]: table::boot::BootServices
//! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc
//! [`SystemTable`]: table::SystemTable
Expand Down
0