Add in-depth guide for ngAria

[marcysutton]

To help explain what the ngAria module can and can't do, I've updated the Developer Guide to include more in-depth information, code examples and accessibility resources. This is a companion piece to a blog post on the official AngularJS blog due out shortly.

Related to #9925

[caitp]

could we wrap these lines at 100cols so it's a bit easier to review?

[marcysutton]

Done!

[caitp]

These looks pretty good --- I would still like to see more content in the API docs section for ngAria, especially code examples, and a specific list of each core directive which is "overloaded", and in what capacity.

But the guide looks great. Note you'll want to add it to the TOC on https://github.com/angular/angular.js/blob/master/docs/content/guide/index.ngdoc --- and it would be really cool if we had a link to it on the docs index page to highlight it, too.

[marcysutton]

@caitp great suggestions. Isn't that TOC the docs index page or is there another one? I have added a link to the guide index page that you linked. I can do a pass on the API documentation but it may have to come after this PR.

[caitp]

The guide index page should be fine --- but the other index page is https://github.com/angular/angular.js/blob/master/docs/content/api/index.ngdoc -- there's a little overview of each module, but ngAria is missing.

That stuff can wait for another PR, this is good so I'd like to land it.

[btford]

LGTM

[petebacondarwin]

LGTM - Thanks @marcysutton

[marcysutton]

@caitp should $ariaProvider be added to the Provider components doc? https://docs.angularjs.org/api/ng/provider

[caitp]

I believe that page is generated automatically --- @petebacondarwin am I wrong about that? I think all you need is doc-annotated comments on the $ariaProvider.

[marcysutton]

That would make much more sense. No human should be generating these HTML tables, let alone reading them. :)

[gkalpak]

@marcysutton:
The doc you link to is for providers in the ng module (and this is not where $ariaProvider belongs).
The corresponding section for the ngAria module is https://docs.angularjs.org/api/ngAria/provider (and $ariaProvider is indeed listed there).

[marcysutton]

Hi @gkalpak, I'm not sure I follow. The config link on L128 of this Developer Guide gets the user to currently-available information without having to follow a trail of links around--is there a convention for docs contributors that I'm missing? The API documentation will be updated later this week, providing more content that can be linked to directly from this guide.

[gkalpak]

@marcysutton: Now, I am not sure I follow. The config link seems fine and should take people to https://docs.angularjs.org/api/ngAria/provider/$ariaProvider (the docs on $ariaProvider), as expected.
This is fine.

---

In my comment, I was referring to #9930 (comment):

@caitp should $ariaProvider be added to the Provider components doc? https://docs.angularjs.org/api/ng/provider

Expanding on my previous comment (for the sake of clarity):

$ariaProvider should not be added to the Provider components doc at https://docs.angularjs.org/api/ng/provider (<--- this is the link you used in your question), because it refers to the Providers in the ng module (core).

$ariaProvider belongs to the ngAria module (as you know better than me 😸) and therefore it should appear in the Provider components doc for the ngAria module (at https://docs.angularjs.org/api/ngAria/provider).
And indeed it already appears there, since it is correctly ngdoc-annotated (as provider of the ngAria module). Therefore, you don't need to do anything manually.

_{I hope this clears it up. Let me know if it doesn't 😃}

[marcysutton]

@gkalpak gotcha! That makes sense, thank you for the clarification.