start each base class documentation with one-line summary

[stuartcampbell]

Original reporter: prjemian

Propose to start the documentation of each base class (and other NXDL files, too) with a one-line summary. With that, then the page that lists all the base classes together at the start of the base class documentation in the manual, could show this summary. This page:

http://download.nexusformat.org/doc/html/classes/base_classes/index.html

will become much more informative for the community and still be fully generated from source file.

[zjttoefs]

I think that's a good idea. If there was an example of how that would need to be formatted writing the texts would be easy.

[prjemian]

tested OK on Linux - manual page built properly

still inconsistencies in use of "template" v. "description", as well as lower/upper case at start of doc summary - fix those and then submit for PR

[prjemian]

also, will test on Windows as part of those last consistency changes to make

[zjttoefs]

Reopened to gather opinions on the right start of those one-line summaries at the next telco.

[rayosborn]

I'm sorry I haven't had time to look at this closely yet, but I think Pete has made a great start. There are a couple of minor tweaks that I would recommend in the wording. We should probably decide if we are going to explicitly define whether components are specific to neutrons or x-rays and then be consistent in implementing this. NXmoderator is always a neutron moderator, for example, whereas I guess NXfresnel_zone_plate is always an x-ray component. I'm also not sure that the NXmonochromator description is ideal. There are so many small changes we could suggest that perhaps this should be delayed until the NIAC meeting.

[prjemian]

To enable the infrastructure, one line summaries were created from the existing documentation. Attempt was made to make the summary text consistent amongst the various base classes.

Discussion of the descriptive summary wording for each NXDL file is separate from this issue and should be discussed separately. This issue is about creating and installing the infrastructure to make this change in the reference documentation. That infrastructure has been accepted in a recent merge, noted above.

I am closing this issue as complete. Please create a new issue to discuss the documentation of any particular base class that needs further revision.