documenting name/description calculations in the HTML to accessibility API guide

Hi all,

I contacted Alex Surkov one of the mozilla accessibility engineers about
how he would like to see name/description calculation algorithms documented
(as he is one of the target audience) in the HTML to accessibility API
guide [1] ;

I aksed him to review this in which I attempted (note i say attempted) to
use the prose style and be specific a la hixie:

[1] https://dvcs.w3.org/hg/html-api-map/raw-file/tip/Overview.html
5.4 Figure and figcaption elements

If the figure element has an
aria-label<http://www.w3.org/TR/wai-aria/states_and_properties#aria-label>or
an
aria-labelledby<http://www.w3.org/TR/wai-aria/states_and_properties#aria-labelledby>attribute
the accessible name is to be calculated using the algorithm
defined in section 5.2.7. Accessible Name
Calculation<http://www.w3.org/TR/wai-aria/roles#namecalculation>of the
WAI-ARIA
1.0 specification <http://www.w3.org/TR/wai-aria/>.

   - If the figure element does not contain a non-empty figcaption element
   or a non-empty title attribute the figure element's accessible name is
   an empty string and the figure element's accessible description is an
   empty string.
   - If the figure element does contain a non-empty figcaption element, but
   not a non-empty title attribute, use the content of the associated
   figcaption element as the figure elements accessible name.
   - If the figure element has a non-empty title attribute, but does not
   contain non-empty figcaption element, use the content of the
titleattribute as the control's accessible name.
   - If the figure element contains a non-empty figcaption element and a
   has non-empty title attribute, use the content of the figcaption element
   as the figure elements accessible name. Use the content of the
titleattribute as the the
   figure elements accessible description.


He came back with this:

Name calculation:

1) use aria-labelledby

2) otherwise use aria-label

3) otherwise use figcaption subtree

4) otherwise use title attribute

Description calculation:

1) use aria-describedby

2) otherwise use title attribute if it wasn't used for a name

His approach appears much less verbose and also clearer, any thoughts? how
could either approach be improved?


-- 
with regards

Steve Faulkner
Technical Director - TPG

www.paciellogroup.com | www.HTML5accessibility.com |
www.twitter.com/stevefaulkner
HTML5: Techniques for providing useful text alternatives -
dev.w3.org/html5/alt-techniques/
Web Accessibility Toolbar - www.paciellogroup.com/resources/wat-ie-about.html