UI: add docs to examples

[nhaagen]

No description provided.

[klees]

I only skimmed the changes, but everything I have read sound plausible.

@nhaagen: Could you explain a little how these changes arose?

[nhaagen]

Hi @klees ,
you personally know all that, but I'll expand for the broader public:

Although the UI is widely covered by unit tests, there is still a large part of manual testing involved.
In order to know about the anticipated behaviour, testers need an informative description of the anticipated behavior,
and/or guidance and instructions on how to operate the component. These instructions are organized in testrail, where every component is assigned two testcases, of which one is the functional testing of the rendered component (the other one is HTML validation).

With 10, we decided to have UI Components generate an import for testrail to setup/update testcases along with changes in components. That transfers the responsibility of updating the testcase to the developer - while she is at it, anyways.

We use the docs in the examples to hold the testcase description, so every developer is asked to add or amend the 'expected output' section of the example docs to fit the changed/introduced behavior of the given example.

Issues within might well be reported in mantis, and I'd also ask @klees, @Amstutz and @thibsy (and whoever will accept contributions to the UI framework) to watch out for missing/erroneous/deficitly rudimentary docs as well.

Best regards,
Nils