Document feature flags using crate document-features (#1725)

Cargo.lock

@@ -1071,6 +1071,12 @@ dependencies = [
  "rand",
 ]
 
+[[package]]
+name = "document-features"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b01c09fd63b5136fba41aa625c7b3254f0aa0a435ff6ec4b2c9a28d496c83c88"
+
 [[package]]
 name = "downcast-rs"
 version = "1.2.0"
@@ -1128,6 +1134,7 @@ dependencies = [
  "bytemuck",
  "dark-light",
  "directories-next",
+ "document-features",
  "egui",
  "egui-wgpu",
  "egui-winit",
@@ -1153,6 +1160,7 @@ name = "egui"
 version = "0.18.1"
 dependencies = [
  "ahash 0.7.6",
+ "document-features",
  "epaint",
  "nohash-hasher",
  "ron",
@@ -1165,6 +1173,7 @@ name = "egui-wgpu"
 version = "0.18.0"
 dependencies = [
  "bytemuck",
+ "document-features",
  "egui",
  "pollster",
  "tracing",
@@ -1178,6 +1187,7 @@ name = "egui-winit"
 version = "0.18.0"
 dependencies = [
  "arboard",
+ "document-features",
  "egui",
  "instant",
  "puffin",
@@ -1215,6 +1225,7 @@ version = "0.18.0"
 dependencies = [
  "chrono",
  "criterion",
+ "document-features",
  "egui",
  "egui_extras",
  "enum-map",
@@ -1229,6 +1240,7 @@ name = "egui_extras"
 version = "0.18.0"
 dependencies = [
  "chrono",
+ "document-features",
  "egui",
  "image",
  "resvg",
@@ -1244,6 +1256,7 @@ version = "0.18.0"
 dependencies = [
  "ahash 0.7.6",
  "bytemuck",
+ "document-features",
  "egui",
  "egui-winit",
  "glium",
@@ -1255,6 +1268,7 @@ name = "egui_glow"
 version = "0.18.1"
 dependencies = [
  "bytemuck",
+ "document-features",
  "egui",
  "egui-winit",
  "glow",
@@ -1290,6 +1304,7 @@ name = "emath"
 version = "0.18.0"
 dependencies = [
  "bytemuck",
+ "document-features",
  "mint",
  "serde",
 ]
@@ -1361,6 +1376,7 @@ dependencies = [
  "cint",
  "color-hex",
  "criterion",
+ "document-features",
  "emath",
  "nohash-hasher",
  "parking_lot 0.12.0",

eframe/Cargo.toml

@@ -22,16 +22,17 @@ all-features = true
 [features]
 default = ["default_fonts", "glow"]
 
-# detect dark mode system preference
+## Detect dark mode system preference using [`dark-light`](https://docs.rs/dark-light).
 dark-light = ["dep:dark-light"]
 
-# If set, egui will use `include_bytes!` to bundle some fonts.
+## If set, egui will use `include_bytes!` to bundle some fonts.
-# If you plan on specifying your own fonts you may disable this feature.
+## If you plan on specifying your own fonts you may disable this feature.
 default_fonts = ["egui/default_fonts"]
 
+## Use [`glow`](https://github.com/grovesNL/glow) for painting, via [`egui_glow`](https://github.com/emilk/egui/tree/master/egui_glow).
 glow = ["dep:glow", "egui_glow"]
 
-# Enable saving app state to disk.
+## Enable saving app state to disk.
 persistence = [
   "directories-next",
   "egui-winit/serde",
@@ -40,29 +41,34 @@ persistence = [
   "serde",
 ]
 
-# Enable profiling with the puffin crate: https://github.com/EmbarkStudios/puffin
+## Enable profiling with the [`puffin`](https://docs.rs/puffin) crate.
-# Only enabled on native, because of the low resolution (1ms) of time keeping in browsers.
+##
-# eframe will call `puffin::GlobalProfiler::lock().new_frame()` for you
+## Only enabled on native, because of the low resolution (1ms) of time keeping in browsers.
+## `eframe` will call `puffin::GlobalProfiler::lock().new_frame()` for you
 puffin = ["dep:puffin", "egui_glow/puffin"]
 
-# enable screen reader support (requires `ctx.options().screen_reader = true;`)
+## Enable screen reader support (requires `ctx.options().screen_reader = true;`)
 screen_reader = [
   "egui-winit/screen_reader",
   "tts",
 ]
 
-# Use WGPU as the backend instead of glow
+## Use [`wgpu`](https://docs.rs/wgpu) for painting (via [`egui_wgpu`](https://github.com/emilk/egui/tree/master/egui_wgpu)).
+## This overrides the `glow` feature.
 wgpu = ["dep:wgpu", "egui-wgpu"]
 
 
 [dependencies]
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"
+
 egui = { version = "0.18.0", path = "../egui", default-features = false, features = [
   "bytemuck",
   "tracing",
 ] }
 tracing = "0.1"
 
-# optional:
+#! ### Optional dependencies
 egui_glow = { version = "0.18.0", path = "../egui_glow", optional = true, default-features = false }
 egui-wgpu = { version = "0.18.0", path = "../egui-wgpu", optional = true, features = ["winit"] }
 glow = { version = "0.11", optional = true }
@@ -133,6 +139,6 @@ web-sys = { version = "0.3.52", features = [
   "Window",
 ] }
 
-# optional:
+# optional
 # feature screen_reader
 tts = { version = "0.20", optional = true } # stuck on old version due to compilation problems on linux

eframe/src/lib.rs

@@ -52,6 +52,10 @@
 //!     eframe::start_web(canvas_id, Box::new(|cc| Box::new(MyApp::new(cc))))
 //! }
 //! ```
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::needless_doctest_main)]
 

egui-wgpu/Cargo.toml

@@ -28,11 +28,14 @@ all-features = true
 
 
 [features]
-# Make it easy to create bindings for winit.
+## Enable [`winit`](https://docs.rs/winit) integration.
 winit = ["dep:pollster", "dep:winit"]
 
 
 [dependencies]
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"
+
 egui = { version = "0.18.1", path = "../egui", default-features = false, features = [
     "bytemuck",
 ] }
@@ -42,6 +45,6 @@ tracing = "0.1"
 type-map = "0.5.0"
 wgpu = { version = "0.12", features = ["webgl"] }
 
-# Optional:
+#! ### Optional dependencies
 pollster = { version = "0.2", optional = true }
 winit = { version = "0.26", optional = true }

egui-wgpu/src/lib.rs

@@ -1,4 +1,8 @@
 //! This crates provides bindings between [`egui`](https://github.com/emilk/egui) and [wgpu](https://crates.io/crates/wgpu).
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(unsafe_code)]
 

egui-winit/Cargo.toml

@@ -20,27 +20,30 @@ all-features = true
 [features]
 default = ["clipboard", "links"]
 
-# implement bytemuck on most types.
+## [`bytemuck`](https://docs.rs/bytemuck) enables you to cast [`egui::epaint::Vertex`], [`egui::Vec2`] etc to `&[u8]`.
 bytemuck = ["egui/bytemuck"]
 
-# enable cut/copy/paste to OS clipboard.
+## Enable cut/copy/paste to OS clipboard.
-# if disabled a clipboard will be simulated so you can still copy/paste within the egui app.
+## If disabled a clipboard will be simulated so you can still copy/paste within the egui app.
 clipboard = ["arboard", "smithay-clipboard"]
 
-# enable opening links in a browser when an egui hyperlink is clicked.
+## Enable opening links in a browser when an egui hyperlink is clicked.
 links = ["webbrowser"]
 
-# enable profiling with the puffin crate: https://github.com/EmbarkStudios/puffin
+## Enable profiling with the [`puffin`](https://docs.rs/puffin) crate.
 puffin = ["dep:puffin"]
 
-# experimental support for a screen reader
+## Experimental support for a screen reader.
 screen_reader = ["tts"]
 
-# to serialize `WindowSettings`
+## Allow serialization of [`WindowSettings`] using [`serde`](https://docs.rs/serde).
 serde = ["egui/serde", "dep:serde"]
 
 
 [dependencies]
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"
+
 egui = { version = "0.18.0", path = "../egui", default-features = false, features = [
   "tracing",
 ] }

egui-winit/src/lib.rs

@@ -2,6 +2,10 @@
 //!
 //! The library translates winit events to egui, handled copy/paste,
 //! updates the cursor, open links clicked in egui, etc.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::manual_range_contains)]
 

egui/Cargo.toml

@@ -22,45 +22,48 @@ all-features = true
 [features]
 default = ["default_fonts"]
 
-# add compatibility with https://crates.io/crates/cint
+## [`bytemuck`](https://docs.rs/bytemuck) enables you to cast [`epaint::Vertex`], [`emath::Vec2`] etc to `&[u8]`.
-cint = ["epaint/cint"]
-
-# implement bytemuck on most types.
 bytemuck = ["epaint/bytemuck"]
 
-# This will automatically detect deadlocks due to double-locking on the same thread.
+## [`cint`](https://docs.rs/cint) enables interopability with other color libraries.
-# If your app freezes, you may want to enable this!
+cint = ["epaint/cint"]
-# Only affects `epaint::mutex::RwLock` (which egui uses a lot).
-deadlock_detection = ["epaint/deadlock_detection"]
 
-# If set, egui will use `include_bytes!` to bundle some fonts.
+## Enable the [`hex_color`] macro.
-# If you plan on specifying your own fonts you may disable this feature.
-default_fonts = ["epaint/default_fonts"]
-
-# Enable additional checks if debug assertions are enabled (debug builds).
-extra_debug_asserts = ["epaint/extra_debug_asserts"]
-# Always enable additional checks.
-extra_asserts = ["epaint/extra_asserts"]
-
-# Add compatability with https://github.com/kvark/mint
-mint = ["epaint/mint"]
-
-# enable persistence of memory (window positions etc).
-persistence = ["serde", "epaint/serde", "ron"]
-
-# implement serde on most types.
-serde = ["dep:serde", "epaint/serde"]
-
-# Ease of use hex to Color32 macro
 color-hex = ["epaint/color-hex"]
 
+## This will automatically detect deadlocks due to double-locking on the same thread.
+## If your app freezes, you may want to enable this!
+## Only affects [`epaint::mutex::RwLock`] (which egui uses a lot).
+deadlock_detection = ["epaint/deadlock_detection"]
+
+## If set, egui will use `include_bytes!` to bundle some fonts.
+## If you plan on specifying your own fonts you may disable this feature.
+default_fonts = ["epaint/default_fonts"]
+
+## Enable additional checks if debug assertions are enabled (debug builds).
+extra_debug_asserts = ["epaint/extra_debug_asserts"]
+## Always enable additional checks.
+extra_asserts = ["epaint/extra_asserts"]
+
+## [`mint`](https://docs.rs/mint) enables interopability with other math libraries such as [`glam`](https://docs.rs/glam) and [`nalgebra`](https://docs.rs/nalgebra).
+mint = ["epaint/mint"]
+
+## Enable persistence of memory (window positions etc).
+persistence = ["serde", "epaint/serde", "ron"]
+
+## Allow serialization using [`serde`](https://docs.rs/serde).
+serde = ["dep:serde", "epaint/serde"]
+
 [dependencies]
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"
+
 epaint = { version = "0.18.1", path = "../epaint", default-features = false }
 
 ahash = "0.7"
 nohash-hasher = "0.2"
 
-# Optional:
+#! ### Optional dependencies
 ron = { version = "0.7", optional = true }
 serde = { version = "1", optional = true, features = ["derive", "rc"] }
 # egui doesn't log much, but when it does, it uses `tracing`

egui/src/lib.rs

@@ -291,6 +291,10 @@
 //! }); // the temporary settings are reverted here
 //! # });
 //! ```
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::float_cmp)]
 #![allow(clippy::manual_range_contains)]

egui_demo_lib/Cargo.toml

@@ -23,11 +23,16 @@ all-features = true
 default = []
 
 chrono = ["egui_extras/datepicker", "dep:chrono"]
+## Allow serialization using [`serde`](https://docs.rs/serde).
 serde = ["egui/serde", "dep:serde"]
+## Enable better syntax highlighting using [`syntect`](https://docs.rs/syntect).
 syntax_highlighting = ["syntect"]
 
 
 [dependencies]
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"
+
 egui = { version = "0.18.0", path = "../egui", default-features = false }
 egui_extras = { version = "0.18.0", path = "../egui_extras" }
 enum-map = { version = "2", features = ["serde"] }

egui_demo_lib/src/lib.rs

@@ -3,6 +3,10 @@
 //! This library can be used to test 3rd party egui integrations (see for instance <https://github.com/not-fl3/egui-miniquad/blob/master/examples/demo.rs>).
 //!
 //! The demo is also used in benchmarks and tests.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::float_cmp)]
 #![allow(clippy::manual_range_contains)]

egui_extras/Cargo.toml

@@ -26,29 +26,33 @@ all-features = true
 [features]
 default = []
 
-# Datepicker widget
+## Enable [`DatePickerButton`] widget.
 datepicker = ["chrono"]
 
+## Allow serialization using [`serde`](https://docs.rs/serde).
 serde = ["dep:serde"]
 
-# Support loading svg images
+## Support loading svg images.
 svg = ["resvg", "tiny-skia", "usvg"]
 
-# Log warnings using `tracing` crate
+## Log warnings using `tracing` crate.
 tracing = ["dep:tracing", "egui/tracing"]
 
 
 [dependencies]
 egui = { version = "0.18.0", path = "../egui", default-features = false }
 
-# Optional dependencies:
+#! ### Optional dependencies
 
 # Date operations needed for datepicker widget
 chrono = { version = "0.4", optional = true }
 
-# Add support for loading images with the `image` crate.
+## Add support for loading images with the [`image`](https://docs.rs/image) crate.
-# You also need to ALSO opt-in to the image formats you want to support, like so:
+##
-#     image = { version = "0.24", features = ["jpeg", "png"] }
+## You also need to ALSO opt-in to the image formats you want to support, like so:
+## ```toml
+## image = { version = "0.24", features = ["jpeg", "png"] }
+## ```
 image = { version = "0.24", optional = true, default-features = false }
 
 # svg feature
@@ -61,3 +65,6 @@ serde = { version = "1", features = ["derive"], optional = true }
 
 # feature "tracing"
 tracing = { version = "0.1", optional = true }
+
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"

egui_extras/src/lib.rs

@@ -1,4 +1,10 @@
-//! This is a crate that adds some features on top top of [`egui`](https://github.com/emilk/egui). This crate are for experimental features, and features that require big dependencies that does not belong in `egui`.
+//! This is a crate that adds some features on top top of [`egui`](https://github.com/emilk/egui).
+//!
+//! This crate are for experimental features, and features that require big dependencies that does not belong in `egui`.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::float_cmp)]
 #![allow(clippy::manual_range_contains)]

egui_glium/Cargo.toml

@@ -26,18 +26,22 @@ all-features = true
 [features]
 default = ["clipboard", "links"]
 
-# enable cut/copy/paste to OS clipboard.
+## Enable cut/copy/paste to OS clipboard.
-# if disabled a clipboard will be simulated so you can still copy/paste within the egui app.
+##
+## If disabled a clipboard will be simulated so you can still copy/paste within the egui app.
 clipboard = ["egui-winit/clipboard"]
 
-# enable opening links in a browser when an egui hyperlink is clicked.
+## Enable opening links in a browser when an egui hyperlink is clicked.
 links = ["egui-winit/links"]
 
-# experimental support for a screen reader.
+## Experimental support for a screen reader.
 screen_reader = ["egui-winit/screen_reader"]
 
 
 [dependencies]
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"
+
 egui = { version = "0.18.0", path = "../egui", default-features = false, features = [
   "bytemuck",
 ] }
@@ -47,6 +51,5 @@ ahash = "0.7"
 bytemuck = "1.7"
 glium = "0.31"
 
-
 [dev-dependencies]
 image = { version = "0.24", default-features = false, features = ["png"] }

egui_glium/src/lib.rs

@@ -3,6 +3,10 @@
 //! The main type you want to use is [`EguiGlium`].
 //!
 //! If you are writing an app, you may want to look at [`eframe`](https://docs.rs/eframe) instead.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::float_cmp)]
 #![allow(clippy::manual_range_contains)]

egui_glow/Cargo.toml

@@ -26,26 +26,30 @@ all-features = true
 [features]
 default = []
 
-# for the winit integration:
+## For the `winit` integration:
-# enable cut/copy/paste to os clipboard.
+## enable cut/copy/paste to os clipboard.
-# if disabled a clipboard will be simulated so you can still copy/paste within the egui app.
+##
+## if disabled a clipboard will be simulated so you can still copy/paste within the egui app.
 clipboard = ["egui-winit?/clipboard"]
 
-# for the winit integration:
+## For the `winit` integration:
-# enable opening links in a browser when an egui hyperlink is clicked.
+## enable opening links in a browser when an egui hyperlink is clicked.
 links = ["egui-winit?/links"]
 
-# experimental support for a screen reader.
+## Experimental support for a screen reader.
 screen_reader = ["egui-winit?/screen_reader"]
 
-# enable profiling with the puffin crate: https://github.com/embarkstudios/puffin
+## Enable profiling with the [`puffin`](https://docs.rs/puffin) crate.
 puffin = ["dep:puffin", "egui-winit?/puffin"]
 
-# enable winit integration.
+## Enable [`winit`](https://docs.rs/winit) integration.
 winit = ["egui-winit",]
 
 
 [dependencies]
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"
+
 egui = { version = "0.18.0", path = "../egui", default-features = false, features = [
   "bytemuck",
 ] }

egui_glow/src/lib.rs

@@ -3,6 +3,10 @@
 //! The main types you want to look are are [`Painter`] and [`EguiGlow`].
 //!
 //! If you are writing an app, you may want to look at [`eframe`](https://docs.rs/eframe) instead.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::float_cmp)]
 #![allow(clippy::manual_range_contains)]

emath/Cargo.toml

@@ -22,14 +22,23 @@ all-features = true
 [features]
 default = []
 
-# Enable additional checks if debug assertions are enabled (debug builds).
+## Enable additional checks if debug assertions are enabled (debug builds).
 extra_debug_asserts = []
-# Always enable additional checks.
+## Always enable additional checks.
 extra_asserts = []
 
 
 [dependencies]
-# Optional:
+#! ### Optional dependencies
+
+## [`bytemuck`](https://docs.rs/bytemuck) enables you to cast `emath` types to `&[u8]`.
 bytemuck = { version = "1.7.2", optional = true, features = ["derive"] }
+
+## [`mint`](https://docs.rs/mint) enables interopability with other math libraries such as [`glam`](https://docs.rs/glam) and [`nalgebra`](https://docs.rs/nalgebra).
 mint = { version = "0.5.6", optional = true }
+
+## Allow serialization using [`serde`](https://docs.rs/serde).
 serde = { version = "1", optional = true, features = ["derive"] }
+
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"

emath/src/lib.rs

@@ -14,6 +14,10 @@
 //!
 //! For that, use something else ([`glam`](https://docs.rs/glam), [`nalgebra`](https://docs.rs/nalgebra), …)
 //! and enable the `mint` feature flag in `emath` to enable implicit conversion to/from `emath`.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::float_cmp)]
 #![allow(clippy::manual_range_contains)]

epaint/Cargo.toml

@@ -29,40 +29,49 @@ all-features = true
 [features]
 default = ["default_fonts"]
 
-# implement bytemuck on most types.
+## [`bytemuck`](https://docs.rs/bytemuck) enables you to cast [`Vertex`] to `&[u8]`.
 bytemuck = ["dep:bytemuck", "emath/bytemuck"]
 
-# This will automatically detect deadlocks due to double-locking on the same thread.
+## This will automatically detect deadlocks due to double-locking on the same thread.
-# If your app freezes, you may want to enable this!
+## If your app freezes, you may want to enable this!
-# Only affects `epaint::mutex::RwLock` (which epaint and egui uses a lot).
+## Only affects [`mutex::RwLock`] (which epaint and egui uses a lot).
 deadlock_detection = ["dep:backtrace"]
 
-# If set, epaint will use `include_bytes!` to bundle some fonts.
+## If set, epaint will use `include_bytes!` to bundle some fonts.
-# If you plan on specifying your own fonts you may disable this feature.
+## If you plan on specifying your own fonts you may disable this feature.
 default_fonts = []
 
-# Enable additional checks if debug assertions are enabled (debug builds).
+## Enable additional checks if debug assertions are enabled (debug builds).
 extra_debug_asserts = ["emath/extra_debug_asserts"]
-# Always enable additional checks.
+## Always enable additional checks.
 extra_asserts = ["emath/extra_asserts"]
 
-# Add compatability with https://github.com/kvark/mint
+## [`mint`](https://docs.rs/mint) enables interopability with other math libraries such as [`glam`](https://docs.rs/glam) and [`nalgebra`](https://docs.rs/nalgebra).
 mint = ["emath/mint"]
 
-# implement serde on most types.
+## Allow serialization using [`serde`](https://docs.rs/serde).
 serde = ["dep:serde", "ahash/serde", "emath/serde"]
 
 [dependencies]
+# Needed when generating the docs, but unfortunately also needed by `cargo check`
+document-features = "0.2"
+
 emath = { version = "0.18.0", path = "../emath" }
 
 ab_glyph = "0.2.11"
 ahash = { version = "0.7", default-features = false, features = ["std"] }
 nohash-hasher = "0.2"
 
-# Optional:
+#! ### Optional dependencies
 bytemuck = { version = "1.7.2", optional = true, features = ["derive"] }
+
+## [`cint`](https://docs.rs/cint) enables interopability with other color libraries.
 cint = { version = "0.3.1", optional = true }
+
+## Enable the [`hex_color`] macro.
 color-hex = { version = "0.2.0", optional = true }
+
+## Allow serialization using [`serde`](https://docs.rs/serde) .
 serde = { version = "1", optional = true, features = ["derive", "rc"] }
 
 # native:

epaint/src/lib.rs

@@ -4,6 +4,10 @@
 //!
 //! Create some [`Shape`]:s and pass them to [`tessellate_shapes`] to generate [`Mesh`]:es
 //! that you can then paint using some graphics API of your choice (e.g. OpenGL).
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![allow(clippy::float_cmp)]
 #![allow(clippy::manual_range_contains)]