Skip to content

Commit

Permalink
fix(common): Various documentation fixes and improvements (#111)
Browse files Browse the repository at this point in the history 
Co-authored-by: str4d <[email protected]>
  • Loading branch information
@str4d
Matt Campbell and str4d authored Jul 19, 2022
1 parent b610a4b commit 4d27234
Showing 1 changed file with 61 additions and 31 deletions.
92 changes: 61 additions & 31 deletions common/src/lib.rs
View file
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".
#[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

0 comments on commit 4d27234

Please sign in to comment.