Questions about the .chm file

UPDATE:

As mentioned in my opening post, I'm trying to clarify the usage (and difference) between two very similar functions:  USBDHIDInit versus USBDHIDCompositeInit.

I discovered some hints of clarification by examining the parallel functions specifically for a mouse device:  USBDHIDMouseInit versus USBDHIDMouseCompositeInit. Under the latter function, the .chm help file says this:

This call is very similar to USBDHIDMouseInit() except that it is used for initializing an instance of the HID mouse device for
use in a composite device. [Walter comments: The .chm file doesn't illuminate how to do that.]

Returns:

Returns zero on failure or a non-zero instance value that should be used
with the remaining USB HID Mouse APIs. [Walter comments: The .chm file
doesn't illuminate what a "non-zero instance value" is or how to use it to initialize
any remaining USB HID mouse APIs.]

Since my USB port is to mimic a single USB HID device -- not multiple HID devices, and not a composite device -- then perhaps I am safe by merely using the one function, USBDHIDInit, (and completely ignore the USBDHIDCompositeInit function). ??? However, the mouse example from the StarterWare package calls BOTH initialization routines, even though it is likewise a single, non-composite device. It initializes the mouse twice: once with each function.  So I remain confused. What is the difference between the Init versus CompositeInit functions?  And how are we to use these?

Max,

Thanks for your help. This forum, and the help you guys give, is a major reason why I'm a big TI fan. 

Yes, the word "Composite" (as in USBDHIDCompositeInit) was confusing to me. I presumed it had something
to do with initializing composite USB devices. Such as a keyboard with a built-in trackball, both using the same
USB controller -- thus they together represent a "composite" device. I presumed that was the meaning, so
I couldn't figure out the proper way to use these function calls.  Also, the identical descriptions of the two
functions (in the .chm file) made it hard to differentiate between the two functions.

I had previously thought (mistakenly) that the .chm file represented the entirety of my access to knowledge
about the API -- the .chm file is intended as a complete description of how I am to use the APIs.  I assumed
(mistakenly) that the source code for the API libraries was unavailable to us, and that the deep dark bowels
of the code could not be knowable to us.  (Which would ordinarily be fine with me, as I really DON'T want to be
overwhelmed with minutiae about USB.)  But with your suggestion, I poked around some more and
located the source files in question.  So indeed, examination of the source code does over another avenue
for understanding things.

While I am grateful for that (as this StarterWare is a huge step forward for using USB), I also would hope for
a better description within the .chm file itself. I want the APIs to HIDE the deeper information about USB, so I
need not know about it. I just want to know the bare minimum for what I need to get done. (Information hiding
is typically one of the goals of object-oriented programming design.)

Let me give a relevant example. The USB API returns various event codes to me (indicating errors, idle,
resume, suspend, and so forth). And I need to handle those somehow. But, the .chm file grants no insight
on how to confidently do that. For example, I am concerned that my handling might cause the USB to 'lockup'
because I handled something wrong. Such as I'm waiting for the USB controller or Host system to do
something, and they are waiting for me to do something -- so it locks up waiting. The .chm file could give
some meta-level (overview) understanding of these matters, so that we developers could be more
confident (and without having to read source code for the various USB libraries.......). That's my suggestion
anyway.

Max thank you for your help.

-- w.