Confusion over the many ways to represent channels

Question

So I'm making progress on my task, but figuring out the intent of each of these channel representations is still throwing me for a bit of a loop.  So far I've run across...
Channel Name      : string       : "MyChannel"
Channel Reference : string       : "[1]/MyChannel"
Channel Number    : integer      : "1"
Channel Object    : object
Channel List      : element list : (seems to be a generic list object)
Channel String    : string       : "1-3,5,7-10"
There are probably more I haven't encountered yet.  VBScript's variant-with-subtype nature is making it harder for me to make sense of how everything fits together.  Frequently I *think* the arguments and data types match up only to find out the scripting engine disagrees with me.  In any case, the various channel representations combined the mix of object-oriented and functional APIs is making my head spin.  On top of that, the documentation doesn't seem to be entirely consistent with the naming conventions it uses.
Does anyone know why there are so many types of channel represenation and what they are each intended to be used for?

Answer 1

Thanks Walter, that does help.  After reading your post and going over the Channel Refences in the help file for the eleventh time, I think I'm understanding it better.  There are still some things that don't make sense to me.  Mostly I think they are either me just not getting it yet or documentation errors.
Example 1
If you type the following code, (and assuming you have at least 3 channel groups)
logfilewrite("----------")
dim chList, chan
set chList = data.GetChannels("[3]/*")
logfilewrite("Count: " & chList.Count)
set chan = chList(
the pop-up help tells you the input parameter is a reference, but finishing that line with,
set chan = chList("[3]/[1]")
results in a type mismatch error.  Just this morning I realized it is actually displaying the help for the GetChannels method, not the ChannelList.Index method like it should.
Example 2
The help for ChnLinGenImp says the return value "is a String variable type. Receives the name of the new channel."
logfilewrite("----------")
dim chans(4), i
for i = 1 to 4
chans(i) = ChnLinGenImp(i, 100, i, 0)
' chans(i) = ChnLinGen(i, i, i, 100)
logfilewrite(chans(i))
next
If you run this script you'll see it actually returns the channel reference, not the channel name.  The ChnLinGen function also claims to return the channel name but instead returns a reference.
Example 3
ChnLinGen and ChnLinGenImp also differ from each other in very important way that the documentation doesn't tell users about.
logfilewrite("----------")
dim chans(4), groups(2), i, j
data.Root.Clear
for j = 1 to 2
set groups(j) = data.Root.ChannelGroups.Add("Group" & j)
data.Root.ChannelGroups(j).Activate
for i = 1 to 4
chans(i) = ChnLinGenImp(i, 100, i, 0)
' chans(i) = ChnLinGen(i, i, i, 100)
logfilewrite(chans(i))
next
next
If you run the script like this you get the results I (and probably most people) expect.  Two groups each with 4 channels.  But when you replace ChnLinGenImp with ChnLinGen and run the script instead of adding channels to the (active) second group, it overwrites the channels in the (inactive) first group.
I had to read the two help pages pretty closely before I understood what is happening.  ChnLinGenImp will always create a new channel in the active group.  The first argument (the crypticly named "GHdChnName") is for what you want the new channel name (as opposed to channel reference) to be.  If the suggested channel name already exists it will append a number to make the new channel name unique.  ChnLinGen's first argument "specifies the result channel," meaning it will accept any argument that resolves to a single channel.  If that channel already exists, it gets overwritten.  ChnLinGen appears to interpret the first i as a channel index rather than a channel name.
Intuitively I expect these two functions to behave similarly.  I understand the ability to generate implied channels may have been added years after generating real channels and it may not have been possible to design the ChnLinGenImp behavior to be the same as ChnLinGen, but they are in the same family of functions and when there are behavioral differences between similar functions those differences need to be highlighted.  Once I understood the behavior of these two functions, the documentation made more sense to me.  It did little to alert me about the differences before the fact.
Incidentally, I know I can get ChnLinGen to behave the same by simply changing the call to something like,
chans(i) = ChnLinGen("[" & j & "]/" & i, i, i, 100)
...but the cost of working with an api isn't driven by how long it takes me to type in the correct code, it's driven by how long it takes me to figure out what the correct code should be.  And while these snippets are clearly contrived examples, I believe they illustrate the underlying problem of an inconsistent api and ambiguous (or sometimes just plain wrong) documentation.
I'm new to DIAdem and I like the customizability, but I sure hope NI can allocate sufficient resources to fix the shortcomings.