API terminology is confusing

[prjemian]

Many terms in the API are confusing, such as the difference (in the nxdl_manager module) between the attributes and xml_attributes dictionaries. The source code could be named and organized so the different features are more recognizable to the programmer. One idea is to re-organize into submodules, similar to the subcommands of the user interface:

    configuration       show configuration details of punx
    demonstrate         demonstrate HDF5 file validation
    structure           structure command deprecated. Use ``tree`` instead
    tree                show tree structure of HDF5 or NXDL file
    update              update the local cache of NeXus definitions
    validate            validate a NeXus file

[prjemian]

What, exactly, should this dictionary contain and how will it be used?

punx/punx/nxdl_manager.py

Line 152 in f0e707d

self.xml_attributes = {}

Consider renaming self.xml_attributes to self.configuration.

This Python structure should contain content that was described in the NXDL XML file but only provide it in a way that will be useful within punx.

How is self.xml_attributes different from self.attributes? Here:

punx/punx/nxdl_manager.py

Line 291 in f0e707d

self.attributes = {}

[prjemian]

The NXDL__attribute class says:

punx/punx/nxdl_manager.py

Line 366 in f0e707d

contents of a *attribute* structure (XML element) in a NXDL XML file

• Verify this is exactly true.
• Change docstring to: Contents of NXDL <attribute>...</attribute> XML element.
• Similar change for other NXDL__... classes
• Describe parameters for each of these classes.