I could use some opinions on a documentation sample

Hello every one
I know this is slightly off topic but I'm working on getting ready to
release a new version of Lib CIM Perl (A Pure Perl CIM client API). Along
with the new features one of the big improvement in this release is I'm
trying to add some meaningful documentation. my goal is to make it
approachable to people who don't fully understand the protocol.

This isn't completely formatted grammar checked or even thoroughly spell
checked yet but its a good example of where im going with the
documentation. I would appreciate any feedback from the community on the
direction I'm going and if its clear enough.

Thanks in Advance
Paul Robert Marino
*EnumerateClassNames*$query->EnumerateClassNames ('name/space','ClassName',
{ 'DeepInheritance' = 0});$query->EnumerateClassNames ('name/space',, {
'DeepInheritance' = 0});
$query->EnumerateClassNames ('name/space','NULL', { 'DeepInheritance' =
0}); $query->EnumerateClassNames ('name/space','ClassName');
$query->EnumerateClassNames ('name/space'); *The EnumerateClassNames method
returns the names of any CIM classes that inherit from the CIM class name
specified in the ClassName or if the ClassName filed is not specified the
it returns the names of all of the base CIM classes in the name space
specified in the name/space field.**The LCP::Query's EnumerateClassNames
method requires 1 fields and has 2 optional fields described as follows.*

 *1) name/space*

The CIM namespace you want to enumerate the class names from

This field is required
 *2) ClassName*

The name of the CIM class you want to enumerate the class names of

This field is optional.

If you don't wish to specify a value but wish to specify the next field you
may leave it empty or set it to 'NULL'

*Note:* This option may not sound like it make sense but its, especially
when you enable the *DeepInheritence* modifier.
 *3) Query Modifiers*

An optional hash reference containing any combination of the following
query modifiers

*3.1) DeepInheritance*
If this modifier is set to 1 (True) and you have specified a class in the
ClassName field then all of the names of any of subclasses that inherit
directly or indirectly from that class will be returned as well.

If this modifier is set to 1 (True) and no class has been specified in the
ClassName field or the ClassName field has explicitly been set to NULL then
the names of all classes in the namespace will be returned.

If this modifier is set to 0 (False) and you have specified a class in the
ClassName field then only the names of the classes which directly inherit
from the one specified will be returned

If this modifier is set to 0 (False) and no class has been specified in the
ClassName field or the ClassName field has explicitly been set to NULL then
only the names of the base classes in the namespace will be returned.

Defaults to 0 (False)
*Implementation Note:*

One of the common complaints about SMI-S is that the class names are not
standardized from one vendor to the next; but this is a half truth.

SMI-S allows a vendor to create their own CIM subclasses of the CIM classes
named the standard. This allows the vendor to add fields for their one
proprietary features and in some cases remove optional fields that do not
apply to their devices. By using the EnumerateClassNames CIM Intrinsic
method with DeepInheritance enabled you can usually figure out very quickly
what the vendor specific CIM class names are, or if you're in doubt just
assume they all are.

For example if I wanted to know the name of the vendor specific version of
CIM_ComputerSystem on a Fedora Linux box with SBLIM and TOG_OpenPegasus
installed I would execute the following query

here is the query I might create.

$query->EnumerateClassNames ('name/space','CIM_ComputerSystem', {
'DeepInheritance' = 1});

Once the query was posted and the results parsed results were either of the
following two results depending on the value of DeepInheritance.

With DeepInheritence set to 0 (False) it returns

"CIM_Cluster", "CIM_VirtualComputerSystem", "CIM_UnitaryComputerSystem",
"Linux_ComputerSystem", "Xen_ComputerSystem", "KVM_ComputerSystem",
"LXC_ComputerSystem"

With DeepInheritence set to 1 (True) it returns

"CIM_Cluster", "PG_ComputerSystem", "CIM_VirtualComputerSystem",
"CIM_UnitaryComputerSystem", "Linux_ComputerSystem", "Xen_ComputerSystem",
"KVM_ComputerSystem", "LXC_ComputerSystem"

Notice with DeepInheritence set to 1 (True) and additional CIM class name
PG_ComputerSystem is included in the results, this is because the super
class for PG_ComputerSystem is CIM_UnitaryComputerSystem and the super
class for CIM_UnitaryComputerSystem is CIM_ComputerSystem

Here is the relivant portions of the raw XML from a GetClass against the
two classes that illistrates the relatinoship.

From the PG_ComputerSystem CIM Class'

<CLASS NAME="PG_ComputerSystem" SUPERCLASS="CIM_UnitaryComputerSystem" >

What that tells me is that CIM_UnitaryComputerSystem class was used as the
initial template for creating the PG_ComputerSystem class
*From the CIM_UnitaryComputerSystem Class.*

<CLASS NAME="CIM_UnitaryComputerSystem" SUPERCLASS="CIM_ComputerSystem" >

What that tells me is that CIM_ComputerSystem class was used as the initial
template for creating the CIM_UnitaryComputerSystem class.

That means that PG_ComputerSystem indirectly inherits from
CIM_ComputerSystem and by enabling DeepInheritance we can see this
relationship by using the EnumerateClassNames method on the
CIM_ComputerSystem class; however without DeepInheritance enabled we can
not.

The great thing about this is it works for standard SBLIM, SMI-S, WMI,
WMWare, etc.. Any standard or API based on CIM is structured in this manner
so the class name discovery process works the same way for all of them.
*See DSP0200 Version 1.3.1 section 5.3.2.10 for details*