From e8ee468cc6ff34d3b174feebd009cc90559ec75b Mon Sep 17 00:00:00 2001 From: Tobias Hunger Date: Thu, 9 Feb 2023 16:58:26 +0100 Subject: [PATCH] xtask: Sort enums when generating enum docs It's much easier for humans to find entries that way! --- docs/langref/src/builtin_enums.md | 223 +++++++++++++++--------------- xtask/src/enumdocs.rs | 61 ++++---- 2 files changed, 147 insertions(+), 137 deletions(-) diff --git a/docs/langref/src/builtin_enums.md b/docs/langref/src/builtin_enums.md index 678c114bfb..b158b9b810 100644 --- a/docs/langref/src/builtin_enums.md +++ b/docs/langref/src/builtin_enums.md @@ -8,64 +8,20 @@ The name of the enum can be omitted in bindings of the type of that enum, or if return value of a callback is of that enum. The default value of each enum type is always the first value. -## `TextHorizontalAlignment` - This enum describes the different types of alignment of text along the horizontal axis. +## `AccessibleRole` -* **`left`**: The text will be aligned with the left edge of the containing box. -* **`center`**: The text will be horizontally centered within the containing box. -* **`right`**: The text will be aligned to the right of the containing box. + This enum represents the different values for the `accessible-role` property, used to describe the + role of an element in the context of assistive technology such as screen readers. -## `TextVerticalAlignment` - - This enum describes the different types of alignment of text along the vertical axis. - -* **`top`**: The text will be aligned to the top of the containing box. -* **`center`**: The text will be vertically centered within the containing box. -* **`bottom`**: The text will be aligned to the bottom of the containing box. - -## `TextWrap` - - This enum describes the how the text wrap if it is too wide to fit in the Text width. - -* **`no-wrap`**: The text will not wrap, but instead will overflow. -* **`word-wrap`**: The text will be wrapped at word boundaries. - -## `TextOverflow` - - This enum describes the how the text appear if it is too wide to fit in the Text width. - -* **`clip`**: The text will simply be clipped. -* **`elide`**: The text will be elided with `…`. - -## `EventResult` - - This enum describes whether an event was rejected or accepted by an event handler. - -* **`reject`**: The event is rejected by this event handler and may then be handled by the parent item -* **`accept`**: The event is accepted and won't be processed further - -## `FillRule` - - This enum describes the different ways of deciding what the inside of a shape described by a path shall be. - -* **`nonzero`**: The ["nonzero" fill rule as defined in SVG](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-rule#nonzero). -* **`evenodd`**: The ["evenodd" fill rule as defined in SVG](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-rule#evenodd) - -## `StandardButtonKind` - - -* **`ok`**: -* **`cancel`**: -* **`apply`**: -* **`close`**: -* **`reset`**: -* **`help`**: -* **`yes`**: -* **`no`**: -* **`abort`**: -* **`retry`**: -* **`ignore`**: +* **`none`**: The element is not accessible. +* **`button`**: The element is a Button or behaves like one. +* **`checkbox`**: The element is a CheckBox or behaves like one. +* **`combobox`**: The element is a ComboBox or behaves like one. +* **`slider`**: The element is a Slider or behaves like one. +* **`spinbox`**: The element is a SpinBox or behaves like one. +* **`tab`**: The element is a Tab or behaves like one. +* **`text`**: The role for a Text element. It is automatically applied. ## `DialogButtonRole` @@ -81,23 +37,52 @@ The default value of each enum type is always the first value. * **`help`**: This is the role of the "Help" button * **`action`**: This is the role of any other button that performs another action. -## `PointerEventKind` +## `EventResult` + + This enum describes whether an event was rejected or accepted by an event handler. + +* **`reject`**: The event is rejected by this event handler and may then be handled by the parent item +* **`accept`**: The event is accepted and won't be processed further + +## `FillRule` + + This enum describes the different ways of deciding what the inside of a shape described by a path shall be. + +* **`nonzero`**: The ["nonzero" fill rule as defined in SVG](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-rule#nonzero). +* **`evenodd`**: The ["evenodd" fill rule as defined in SVG](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-rule#evenodd) + +## `ImageFit` -* **`cancel`**: -* **`down`**: -* **`up`**: +* **`fill`**: +* **`contain`**: +* **`cover`**: -## `PointerEventButton` +## `ImageRendering` - This enum describes the different types of buttons for a pointer event, - typically on a mouse or a pencil. -* **`other`**: A button that is none of left, right or middle. For example - this is used for a fourth button on a mouse with many buttons. -* **`left`**: The left button. -* **`right`**: The right button. -* **`middle`**: The center button. +* **`smooth`**: +* **`pixelated`**: + +## `InputType` + + This enum is used to define the type of the input field. Currently this only differentiates between + text and password inputs but in the future it could be expanded to also define what type of virtual keyboard + should be shown, for example. + +* **`text`**: The default value. This will render all characters normally +* **`password`**: This will render all characters with a character that defaults to "*" + +## `LayoutAlignment` + + Enum representing the alignment property of a BoxLayout or HorizontalLayout + +* **`stretch`**: +* **`center`**: +* **`start`**: +* **`end`**: +* **`space-between`**: +* **`space-around`**: ## `MouseCursor` @@ -135,39 +120,6 @@ The default value of each enum type is always the first value. * **`nesw-resize`**: Bidirectional resize north-east-south-west. * **`nwse-resize`**: Bidirectional resize north-west-south-east. -## `ImageFit` - - -* **`fill`**: -* **`contain`**: -* **`cover`**: - -## `ImageRendering` - - -* **`smooth`**: -* **`pixelated`**: - -## `InputType` - - This enum is used to define the type of the input field. Currently this only differentiates between - text and password inputs but in the future it could be expanded to also define what type of virtual keyboard - should be shown, for example. - -* **`text`**: The default value. This will render all characters normally -* **`password`**: This will render all characters with a character that defaults to "*" - -## `LayoutAlignment` - - Enum representing the alignment property of a BoxLayout or HorizontalLayout - -* **`stretch`**: -* **`center`**: -* **`start`**: -* **`end`**: -* **`space-between`**: -* **`space-around`**: - ## `PathEvent` PathEvent is a low-level data structure describing the composition of a path. Typically it is @@ -180,19 +132,23 @@ The default value of each enum type is always the first value. * **`end-open`**: The end of the path that remains open. * **`end-closed`**: The end of a path that is closed. -## `AccessibleRole` +## `PointerEventButton` - This enum represents the different values for the `accessible-role` property, used to describe the - role of an element in the context of assistive technology such as screen readers. + This enum describes the different types of buttons for a pointer event, + typically on a mouse or a pencil. -* **`none`**: The element is not accessible. -* **`button`**: The element is a Button or behaves like one. -* **`checkbox`**: The element is a CheckBox or behaves like one. -* **`combobox`**: The element is a ComboBox or behaves like one. -* **`slider`**: The element is a Slider or behaves like one. -* **`spinbox`**: The element is a SpinBox or behaves like one. -* **`tab`**: The element is a Tab or behaves like one. -* **`text`**: The role for a Text element. It is automatically applied. +* **`other`**: A button that is none of left, right or middle. For example + this is used for a fourth button on a mouse with many buttons. +* **`left`**: The left button. +* **`right`**: The right button. +* **`middle`**: The center button. + +## `PointerEventKind` + + +* **`cancel`**: +* **`down`**: +* **`up`**: ## `SortOrder` @@ -203,3 +159,48 @@ The default value of each enum type is always the first value. * **`ascending`**: The column is sorted in ascending order. * **`descending`**: The column is sorted in descending order. +## `StandardButtonKind` + + +* **`ok`**: +* **`cancel`**: +* **`apply`**: +* **`close`**: +* **`reset`**: +* **`help`**: +* **`yes`**: +* **`no`**: +* **`abort`**: +* **`retry`**: +* **`ignore`**: + +## `TextHorizontalAlignment` + + This enum describes the different types of alignment of text along the horizontal axis. + +* **`left`**: The text will be aligned with the left edge of the containing box. +* **`center`**: The text will be horizontally centered within the containing box. +* **`right`**: The text will be aligned to the right of the containing box. + +## `TextOverflow` + + This enum describes the how the text appear if it is too wide to fit in the Text width. + +* **`clip`**: The text will simply be clipped. +* **`elide`**: The text will be elided with `…`. + +## `TextVerticalAlignment` + + This enum describes the different types of alignment of text along the vertical axis. + +* **`top`**: The text will be aligned to the top of the containing box. +* **`center`**: The text will be vertically centered within the containing box. +* **`bottom`**: The text will be aligned to the bottom of the containing box. + +## `TextWrap` + + This enum describes the how the text wrap if it is too wide to fit in the Text width. + +* **`no-wrap`**: The text will not wrap, but instead will overflow. +* **`word-wrap`**: The text will be wrapped at word boundaries. + diff --git a/xtask/src/enumdocs.rs b/xtask/src/enumdocs.rs index bc7ff2038b..fb3ef435f3 100644 --- a/xtask/src/enumdocs.rs +++ b/xtask/src/enumdocs.rs @@ -5,6 +5,37 @@ use anyhow::Context; use std::io::Write; pub fn generate() -> Result<(), Box> { + let mut enums: std::collections::BTreeMap = std::collections::BTreeMap::new(); + + macro_rules! gen_enums { + ($( $(#[doc = $enum_doc:literal])* $(#[non_exhaustive])? enum $Name:ident { $( $(#[doc = $value_doc:literal])* $Value:ident,)* })*) => { + $( + let mut entry = format!("## `{}`\n\n", stringify!($Name)); + $(entry += &format!("{}\n", $enum_doc);)* + entry += "\n"; + $( + let mut has_val = false; + entry += &format!("* **`{}`**:", to_kebab_case(stringify!($Value))); + $( + if has_val { + entry += "\n "; + } + entry += &format!("{}", $value_doc); + has_val = true; + )* + entry += "\n"; + )* + entry += "\n"; + enums.insert(stringify!($Name).to_string(), entry); + )* + } + } + + #[allow(unused)] // for 'has_val' + { + i_slint_common::for_each_enums!(gen_enums); + } + let root = super::root_dir(); let path = root.join("docs/langref/src/builtin_enums.md"); @@ -21,35 +52,13 @@ The name of the enum can be omitted in bindings of the type of that enum, or if return value of a callback is of that enum. The default value of each enum type is always the first value. + "#, )?; - macro_rules! gen_enums { - ($( $(#[doc = $enum_doc:literal])* $(#[non_exhaustive])? enum $Name:ident { $( $(#[doc = $value_doc:literal])* $Value:ident,)* })*) => { - $( - writeln!(file, "## `{}`\n", stringify!($Name))?; - $(writeln!(file, "{}", $enum_doc)?;)* - writeln!(file, "")?; - $( - let mut has_val = false; - write!(file, "* **`{}`**:", to_kebab_case(stringify!($Value)))?; - $( - if has_val { - write!(file, "\n ")?; - } - write!(file, "{}", $value_doc)?; - has_val = true; - )* - writeln!(file, "")?; - )* - writeln!(file, "")?; - )* - } - } - - #[allow(unused)] // for 'has_val' - { - i_slint_common::for_each_enums!(gen_enums); + for (_, v) in enums { + // BTreeMap + write!(file, "{v}")?; } Ok(())