nagai/fune
3
0
Fork 0
forked from mirrors/gecko-dev
Code Pull requests Activity

Bug 1898082: Clean up comments in nsTextEquivUtils, r=Jamie

Browse source 
This revision updates outdated comments in nsTextEquivUtils that refer to
previous names for steps of the Accessible Name and Description Computation
specification. It updates the comments to the new, named computation steps.
Additionally, this revision cleans up and adds other comments to make reading
the code a bit easier.

Differential Revision: https://phabricator.services.mozilla.com/D211110
This commit is contained in:
Nathan LaPre 2024-05-22 17:19:30 +00:00
parent 4a8c40e350
commit 44b945e448
2 changed files with 39 additions and 32 deletions
repo.diff.show_diff_stats Download patch file Download diff file Expand all files Collapse all files

17
accessible/base/nsTextEquivUtils.cpp
View file

@ -20,7 +20,7 @@ using namespace mozilla::a11y;
/**
* The accessible for which we are computing a text equivalent. It is useful
* for bailing out during recursive text computation, or for special cases
* like step f. of the ARIA implementation guide.
* like the "Embedded Control" section of the AccName spec.
*/
static const Accessible* sInitiatorAcc = nullptr;
@ -252,7 +252,7 @@ nsresult nsTextEquivUtils::AppendFromAccessible(Accessible* aAccessible,
bool isEmptyTextEquiv = true;
// Attempt to find the value. If it's non-empty, append and return it. See the
// "embedded control" section of the name spec.
// "Embedded Control" section of the name spec.
nsAutoString val;
nsresult rv = AppendFromValue(aAccessible, &val);
NS_ENSURE_SUCCESS(rv, rv);
@ -261,16 +261,15 @@ nsresult nsTextEquivUtils::AppendFromAccessible(Accessible* aAccessible,
return NS_OK;
}
// If the name is from tooltip then append it to result string in the end
// (see h. step of name computation guide).
// If the name is from tooltip, we retrieve it now but only append it to the
// result string later as a last resort. Otherwise, we append the name now.
nsAutoString text;
if (aAccessible->Name(text) != eNameFromTooltip) {
isEmptyTextEquiv = !AppendString(aString, text);
}
// Implementation of g) step of text equivalent computation guide. Go down
// into subtree if accessible allows "text equivalent from subtree rule" or
// it's not root and not control.
// Implementation of the "Name From Content" step of the text alternative
// computation guide. Traverse the accessible's subtree if allowed.
if (isEmptyTextEquiv) {
if (ShouldIncludeInSubtreeCalculation(aAccessible)) {
rv = AppendFromAccessibleChildren(aAccessible, aString);
@ -280,7 +279,7 @@ nsresult nsTextEquivUtils::AppendFromAccessible(Accessible* aAccessible,
}
}
// Implementation of h. step
// Implementation of the "Tooltip" step
if (isEmptyTextEquiv && !text.IsEmpty()) {
AppendString(aString, text);
if (isHTMLBlock) {
@ -305,7 +304,6 @@ nsresult nsTextEquivUtils::AppendFromValue(Accessible* aAccessible,
// computation. If the given accessible is not the root accessible (the
// accessible the text alternative is computed for in the end) then append the
// accessible value.
if (aAccessible == sInitiatorAcc) {
return NS_OK_NO_NAME_CLAUSE_HANDLED;
}
@ -323,6 +321,7 @@ nsresult nsTextEquivUtils::AppendFromValue(Accessible* aAccessible,
return NS_ERROR_FAILURE;
}
// For other accessibles, get the value directly.
aAccessible->Value(text);
return AppendString(aString, text) ? NS_OK : NS_OK_NO_NAME_CLAUSE_HANDLED;

54
accessible/base/nsTextEquivUtils.h
View file

@ -20,17 +20,19 @@ class LocalAccessible;
} // namespace mozilla
/**
* Text equivalent computation rules (see nsTextEquivUtils::gRoleToNameRulesMap)
* Text equivalent computation rules. These rules are mapped to accessible roles
* in RoleMap.h.
*/
enum ETextEquivRule {
// No rule.
// No rule. Equivalent to "name from author."
eNoNameRule = 0x00,
// Walk into subtree only if the currently navigated accessible is not root
// accessible (i.e. if the accessible is part of text equivalent computation).
eNameFromSubtreeIfReqRule = 0x01,
// Text equivalent computation from subtree is allowed.
// Text equivalent computation from subtree is allowed. Equivalent to "name
// from content."
eNameFromSubtreeRule = 0x03,
// The accessible allows to append its value to text equivalent.
@ -41,7 +43,9 @@ enum ETextEquivRule {
/**
* The class provides utils methods to compute the accessible name and
* description.
* description. Note that, as of the Accessible Name and Description Computation
* 1.2 specification, the phrases "text equivalent" and "text alternative" are
* used interchangably.
*/
class nsTextEquivUtils {
public:
@ -61,7 +65,7 @@ class nsTextEquivUtils {
}
/**
* Calculates the name from accessible subtree if allowed.
* Calculates the name from the given accessible's subtree, if allowed.
*
* @param aAccessible [in] the given accessible
* @param aName [out] accessible name
@ -70,8 +74,10 @@ class nsTextEquivUtils {
nsAString& aName);
/**
* Calculates text equivalent from the subtree. Similar to GetNameFromSubtree.
* However it returns not empty result for things like HTML p.
* Calculates text equivalent from the subtree. This function is similar to
* GetNameFromSubtree, but it returns a non-empty result for things like
* HTML:p, since it does not verify that the given accessible allows name
* from content.
*/
static void GetTextEquivFromSubtree(const Accessible* aAccessible,
nsString& aTextEquiv) {
@ -82,8 +88,8 @@ class nsTextEquivUtils {
}
/**
* Calculates text equivalent for the given accessible from its IDRefs
* attribute (like aria-labelledby or aria-describedby).
* Calculates the text equivalent for the given accessible from one of its
* IDRefs attributes (like aria-labelledby or aria-describedby).
*
* @param aAccessible [in] the accessible text equivalent is computed for
* @param aIDRefsAttr [in] IDRefs attribute on DOM node of the accessible
@ -94,8 +100,8 @@ class nsTextEquivUtils {
nsAString& aTextEquiv);
/**
* Calculates the text equivalent from the given content and its subtree if
* allowed and appends it to the given string.
* Calculates the text equivalent from the given content - and its subtree, if
* allowed - and appends it to the given string.
*
* @param aInitiatorAcc [in] the accessible text equivalent is computed for
* in the end (root accessible of text equivalent
@ -119,8 +125,8 @@ class nsTextEquivUtils {
nsAString* aString);
/**
* Iterates DOM children and calculates text equivalent from each child node.
* Then, appends found text to the given string.
* Iterates DOM children and calculates the text equivalent from each child
* node. Then, appends the calculated text to the given string.
*
* @param aContent [in] the node to fetch DOM children from
* @param aString [in, out] the string
@ -130,33 +136,35 @@ class nsTextEquivUtils {
private:
/**
* Iterates accessible children and calculates text equivalent from each
* child.
* Iterates the given accessible's children and calculates the text equivalent
* from each child. Then, appends the calculated text to the given string.
*/
static nsresult AppendFromAccessibleChildren(const Accessible* aAccessible,
nsAString* aString);
/**
* Calculates text equivalent from the given accessible and its subtree if
* allowed.
* Calculates the text equivalent from the given accessible - and its subtree,
* if allowed. Then, appends the calculated text to the given string.
*/
static nsresult AppendFromAccessible(Accessible* aAccessible,
nsAString* aString);
/**
* Calculates text equivalent from the value of given accessible.
* Calculates the text equivalent from the value of the given accessible.
* Then, appends the calculated text to the given string. This function
* implements the "Embedded Control" section of the AccName spec.
*/
static nsresult AppendFromValue(Accessible* aAccessible, nsAString* aString);
/**
* Calculates text equivalent from the given DOM node and its subtree if
* allowed.
* Calculates the text equivalent from the given DOM node - and its subtree,
* if allowed. Then, appends the calculated text to the given string.
*/
static nsresult AppendFromDOMNode(nsIContent* aContent, nsAString* aString);
/**
* Concatenates strings and appends space between them. Returns true if
* text equivalent string was appended.
* Concatenates the given strings and appends space between them. Returns true
* if the text equivalent string was appended.
*/
static bool AppendString(nsAString* aString,
const nsAString& aTextEquivalent);
@ -173,7 +181,7 @@ class nsTextEquivUtils {
static bool ShouldIncludeInSubtreeCalculation(Accessible* aAccessible);
/**
* Returns true if a given accessible is a text leaf containing only
* Returns true if the given accessible is a text leaf containing only
* whitespace.
*/
static bool IsWhitespaceLeaf(Accessible* aAccessible);