Asking for opinions on documentation I'm writing

[Paul Robert Marino]

Hello every one

I'm getting ready for a second Alpha release of Lib CIM Perl
Its still Alpha because there are still a few aspects of the API I
haven't finalized yet but I'm expecting the to get done latter this
year.
That said one of the things I've been working on is writing
documentation for the intrinsic methods as I've implemented them, and
i just finished the first draft of the new explanation for
EnumerateClassNames
please provide some feed back note I haven't spell or grammar checked
it yet its mostly just a brain dump right now but I want feed back on
this one in particular because its important for new SMI-S developers
to understand, but most don't get right away.



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 sete it to 'NULL'

Note: this may not sound like it make sense but it does 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. so they can add fields for their one
proprietary features. 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.

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 I would wind up
with either one 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 supre class for PG_ComputerSystem is CIM_UnitaryComputerSystem
and the super class for CIM_UnitaryComputerSystem is
CIM_ComputerSystem

here is the relevant portions of the raw XML from a GetClass against
the two classes that illustrate it.

from the PG_ComputerSystem CIM Class

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

From the CIM_UnitaryComputerSystem Class

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

See DSP0200 Version 1.3.1 section 5.3.2.10 for details