More comprehensive docs for ol.DeviceOrientation

[pagameba]

Proposing an extended class description of DeviceOrientation along with
some additional details in the property accessors. Travis is running
its extensive tests, but it passes local linting and doc generation.

[tschaub]

I think the parameter name alpha here is unnecessary. The return should just be the {type} followed by A complete sentence.

[elemoine]

Yes, we just use {type} followed by {A complete sentence} everywhere else.

[tschaub]

Awesome. Curious to see what the effect of the @class annotation is. Will check a build of the docs with/without.

[tschaub]

I see that ol.Map and ol.View2D also use the @class annotation. The effect is that the containing element gets a class-description CSS class name instead of a vanilla description class name. In addition, the description shows up before the "name" (displayed as new DeviceOrientation) when you use the @class annotation. Without the annotation, the description shows up after the name.

With @class:

Without @class:

We're not consistent in the rest of the library, but my preference would be to avoid the extra annotation as it will likely be forgotten in other docs. But we could decide to get consistent and change this across the board in a separate issue.

[tschaub]

This is a really great addition @pagameba. Thanks for the effort. If you get a chance, I do think the generated docs are nicer without the unnecessary parameter name in the return. Either way, it's is certainly worth merging.

[elemoine]

We're not consistent in the rest of the library, but my preference would be to avoid the extra annotation as it will likely be forgotten in other docs. But we could decide to get consistent and change this across the board in a separate issue.

+1 from me for this change.

[pagameba]

I'm ambivalent about the use of @Class, if I had an opinion I would say its a bit nicer to have the class-level stuff before the constructor but I will follow whatever you guys decide is the best pattern. If you want to remove @Class, I can do a pull request to make it consistent through the rest of the docs.

Last commit removes @Class and fixes the pattern for the return types, sorry about that I was thinking of @param when I did it. I also tweaked the text in a couple of places.

[pagameba]

Another commit, this one adds the inline link I wanted near the beginning of the class documentation. I'm still not sure I like this without @Class. Comments?