Question: I've seen a lot of examples which use  

**getAccessibleContext().setAccessibleDescription(...)**  

to set some "magic" description.

What is the use of this description? Where can it be seen and
how should it support accessibility?

Why **setDescription(...)** is not used?

Additionally, what is your opinion / experience with Java accessibility
stuff?

Answer: 
I haven't actually used Swing's accessibility facilities in my applications (and I probably should), but I presume that it will aid in the use of screen readers and other technologies which to improve the accessibility of an application.

From the [Accessibility and the Swing Set](http://java.sun.com/products/jfc/tsc/articles/accessibility/index.html) article:

> 
> If an application fully supports the
>  Java Accessibility API, it can be
>  compatible with, and friendly toward,
>  screen readers, screen magnifiers, and
>  other kinds of assistive technologies.
> 
> 
> 

The linked article goes in to some depth about the accessibility features of Swing and the [Accessibily API](http://java.sun.com/javase/6/docs/api/javax/accessibility/package-summary.html).
As pointed out the accessible information is used to expose information to assistive technologies such as screen readers (in short as a blind computer user I use a screen reader to gather useful information about what control has focus and other useful things happening in a application and then for it to speak it out to me. Examples of screen readers are NVDA www.nvda-project.org for windows, Orca <http://live.gnome.org/Orca> for the gnome desktop on unix platforms and voiceover included by default in MacOSX). For a number of standard controls which contain text you may be able to get away without having to explicitly set accessible information (eg. if you have a button with the text word "OK" then this probably will be spoken fine by a screen reader. The importance of setting accessible information comes in when you have no text showing (eg. a button with a graphic label) or when you are developing a custom control (from memory without going back through some of the Java swing docs, I think the accessible name is to identify the control and accessible description is to provide extra information, may be a clue as how to use it if its a custom control).

Now if you wish to see how this works, NVDA and Orca are opensource projects and voiceover is included in MacOSX 10.4 (I think) and higher, so you can try one of these at no cost (unlike some of the commercial offerings which can be very expensive).