Skip to content

Various documentation fixes and improvements #105

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

Merged
merged 1 commit into from
Jul 19, 2022
Merged

Various documentation fixes and improvements #105

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
92 changes: 61 additions & 31 deletions common/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,7 @@ pub enum Role {
}

/// An action to be taken on an accessibility node.
///
/// In contrast to [`DefaultActionVerb`], these describe what happens to the
/// object, e.g. "focus".
#[derive(EnumSetType, Debug)]
Expand Down Expand Up @@ -301,14 +302,14 @@ pub enum Action {
ScrollIntoView,

/// Scroll the given object to a specified point in the tree's container
/// (e.g. window). /// Requires [`ActionRequest::data`] to be set to
/// (e.g. window). Requires [`ActionRequest::data`] to be set to
/// [`ActionData::ScrollToPoint`].
ScrollToPoint,

/// Requires [`ActionRequest::data`] to be set to [`ActionData::ScrollOffset`].
/// Requires [`ActionRequest::data`] to be set to [`ActionData::SetScrollOffset`].
SetScrollOffset,

/// Requires [`ActionRequest::data`] to be set to [`ActionData::TextSelection`].
/// Requires [`ActionRequest::data`] to be set to [`ActionData::SetTextSelection`].
SetTextSelection,

/// Don't focus this node, but set it as the sequential focus navigation
Expand Down Expand Up @@ -342,7 +343,9 @@ pub enum Orientation {
#[cfg_attr(feature = "serde", serde(crate = "serde"))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum NameFrom {
/// E.g. `aria-label`.
/// E.g. [`aria-label`].
///
/// [`aria-label`]: https://www.w3.org/TR/wai-aria-1.1/#aria-label
Attribute,
AttributeExplicitlyEmpty,
/// E.g. in the case of a table, from a `caption` element.
Expand Down Expand Up @@ -378,7 +381,10 @@ pub enum DescriptionFrom {

/// Function that can be performed when a dragged object is released
/// on a drop target.
/// Note: aria-dropeffect is deprecated in WAI-ARIA 1.1.
///
/// Note: [`aria-dropeffect`] is deprecated in WAI-ARIA 1.1.
///
/// [`aria-dropeffect`]: https://www.w3.org/TR/wai-aria-1.1/#aria-dropeffect
#[derive(EnumSetType, Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
Expand Down Expand Up @@ -418,8 +424,10 @@ pub enum TextDirection {
BottomToTop,
}

/// Indicates if a form control has invalid input or
/// if a web DOM element has an aria-invalid attribute.
/// Indicates if a form control has invalid input or if a web DOM element has an
/// [`aria-invalid`] attribute.
///
/// [`aria-invalid`]: https://www.w3.org/TR/wai-aria-1.1/#aria-invalid
#[derive(Clone, Debug, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
Expand All @@ -444,6 +452,7 @@ pub enum CheckedState {

/// Describes the action that will be performed on a given node when
/// executing the default action, which is a click.
///
/// In contrast to [`Action`], these describe what the user can do on the
/// object, e.g. "press", not what happens to the object as a result.
/// Only one verb can be used at a time to describe the default action.
Expand Down Expand Up @@ -573,15 +582,18 @@ pub enum StringEncoding {
// 128-bit to handle UUIDs.
pub type NodeIdContent = std::num::NonZeroU128;

/// The stable identity of a node, unique within the node's tree.
/// The stable identity of a [`Node`], unique within the node's tree.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
#[cfg_attr(feature = "serde", serde(crate = "serde"))]
pub struct NodeId(pub NodeIdContent);

/// The globally unique ID of a tree. The format of this ID
/// is up to the implementer. A UUID v4 is a safe choice.
/// The globally unique ID of a [`Tree`].
///
/// The format of this ID is up to the implementer. A [v4 UUID] is a safe choice.
///
/// [v4 UUID]: https://datatracker.ietf.org/doc/html/rfc4122#section-4.4
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
Expand All @@ -602,8 +614,10 @@ pub struct TextMarker {
pub range: Range<usize>,
}

/// Defines a custom action for a UI element. For example, a list UI
/// can allow a user to reorder items in the list by dragging the items.
/// Defines a custom action for a UI element.
///
/// For example, a list UI can allow a user to reorder items in the list by dragging the
/// items.
#[derive(Clone, Debug, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
Expand Down Expand Up @@ -668,16 +682,20 @@ pub struct Node {
/// the root node. However, AccessKit expects the final transformed
/// coordinates to be relative to the origin of the tree's container
/// (e.g. window).
///
/// [`bounds`]: Node::bounds
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub transform: Option<Box<Affine>>,
/// The bounding box of this node, in the node's coordinate space.
/// This field does not affect the coordinate space of either this node
/// or its descendants; only the [`transform`] field affects that.
/// This, along with the recommendation that most nodes should have `None`
/// in their [`transform`] field, implies that the [`bounds`] field
/// in their [`transform`] field, implies that the `bounds` field
/// of most nodes should be in the coordinate space of the nearest ancestor
/// with a non-`None` [`Transform`] field, or if there is no such ancestor,
/// with a non-`None` [`transform`] field, or if there is no such ancestor,
/// the tree's container (e.g. window).
///
/// [`transform`]: Node::transform
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub bounds: Option<Rect>,
#[cfg_attr(feature = "serde", serde(default))]
Expand Down Expand Up @@ -707,8 +725,9 @@ pub struct Node {
#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub autofill_available: bool,
/// Whether this node is expanded, collapsed, or neither. Setting this
/// to false means the node is collapsed; omitting it means this state
/// Whether this node is expanded, collapsed, or neither.
///
/// Setting this to `false` means the node is collapsed; omitting it means this state
/// isn't applicable.
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub expanded: Option<bool>,
Expand All @@ -727,6 +746,7 @@ pub struct Node {
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub hovered: bool,
/// Skip over this node in the accessibility tree, but keep its subtree.
///
/// This flag also indicates that this node, but not its descendants,
/// should be skipped when hit testing.
#[cfg_attr(feature = "serde", serde(default))]
Expand Down Expand Up @@ -759,9 +779,10 @@ pub struct Node {
pub busy: bool,

/// The object functions as a text field which exposes its descendants.
///
/// Use cases include the root of a content-editable region, an ARIA
/// textbox which isn't currently editable and which has interactive
/// descendants, and a <body> element that has "design-mode" set to "on".
/// descendants, and a `<body>` element that has "design-mode" set to "on".
Comment on lines -764 to +785
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This is what motivated me to make this PR, as the unescaped <body> tab breaks docs.rs rendering (scroll down a bit).

#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub nonatomic_text_field_root: bool,
Expand All @@ -777,7 +798,7 @@ pub struct Node {
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub live_atomic: bool,

/// If a dialog box is marked as explicitly modal
/// If a dialog box is marked as explicitly modal.
#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub modal: bool,
Expand All @@ -787,9 +808,9 @@ pub struct Node {
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub canvas_has_fallback: bool,

/// Indicates this node is user-scrollable, e.g. overflow:scroll|auto, as
/// opposed to only programmatically scrollable, like overflow:hidden, or
/// not scrollable at all, e.g. overflow:visible.
/// Indicates this node is user-scrollable, e.g. `overflow: scroll|auto`, as
/// opposed to only programmatically scrollable, like `overflow: hidden`, or
/// not scrollable at all, e.g. `overflow: visible`.
#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub scrollable: bool,
Expand All @@ -800,21 +821,22 @@ pub struct Node {
pub clickable: bool,

/// Indicates that this node clips its children, i.e. may have
/// overflow: hidden or clip children by default.
/// `overflow: hidden` or clip children by default.
#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub clips_children: bool,

/// Indicates that this node is not selectable because the style has
/// user-select: none. Note that there may be other reasons why a node is
/// `user-select: none`. Note that there may be other reasons why a node is
/// not selectable - for example, bullets in a list. However, this attribute
/// is only set on user-select: none.
/// is only set on `user-select: none`.
#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub not_user_selectable_style: bool,

/// Indicates whether this node is selected or unselected.
/// The absence of this flag (as opposed to a false setting)
///
/// The absence of this flag (as opposed to a `false` setting)
/// means that the concept of "selected" doesn't apply.
/// When deciding whether to set the flag to false or omit it,
/// consider whether it would be appropriate for a screen reader
Expand All @@ -829,21 +851,28 @@ pub struct Node {
pub selected_from_focus: bool,

/// Indicates whether this node can be grabbed for drag-and-drop operation.
/// Setting this flag to false rather than omitting it means that
///
/// Setting this flag to `false` rather than omitting it means that
/// this node is not currently grabbed but it can be.
/// Note: aria-grabbed is deprecated in WAI-ARIA 1.1.
///
/// Note: [`aria-grabbed`] is deprecated in WAI-ARIA 1.1.
///
/// [`aria-grabbed`]: https://www.w3.org/TR/wai-aria-1.1/#aria-grabbed
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub grabbed: Option<bool>,
/// Note: [`aria-dropeffect`] is deprecated in WAI-ARIA 1.1.
///
/// [`aria-dropeffect`]: https://www.w3.org/TR/wai-aria-1.1/#aria-dropeffect
#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "EnumSet::is_empty"))]
pub drop_effects: EnumSet<DropEffect>,

/// Indicates whether this node causes a hard line-break
/// (e.g. block level elements, or <br>)
/// (e.g. block level elements, or `<br>`).
#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub is_line_breaking_object: bool,
/// Indicates whether this node causes a page break
/// Indicates whether this node causes a page break.
#[cfg_attr(feature = "serde", serde(default))]
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "is_false"))]
pub is_page_breaking_object: bool,
Expand Down Expand Up @@ -1147,7 +1176,7 @@ pub struct Node {
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub font_size: Option<f32>,
/// Font weight can take on any arbitrary numeric value. Increments of 100 in
/// range [0, 900] represent keywords such as light, normal, bold, etc.
/// range `[0, 900]` represent keywords such as light, normal, bold, etc.
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub font_weight: Option<f32>,
/// The text indent of the text, in mm.
Expand Down Expand Up @@ -1346,7 +1375,8 @@ impl Tree {
}
}

/// A serializable representation of an atomic change to a tree.
/// A serializable representation of an atomic change to a [`Tree`].
///
/// The sender and receiver must be in sync; the update is only meant
/// to bring the tree from a specific previous state into its next state.
/// Trying to apply it to the wrong tree should immediately panic.
Expand Down