I have a COM SDK written in C++ and I'd like to create documentation for my product. I understand that most people will probably not use C++ for integration with this COM component, but many will.
Which method is best to describe the API, without losing details that a C++ developer would need to know.
You can write the documentation directly in the IDL using the helpstring attributes - most consumers of your code will be able to read this directly using e.g., OLE View or in their object browser. Our company wrote an internal tool to extract the helpstring documentation and turn it into internal reference documentation in HTML.
Also, you can use a tool like doxygen to document the interfaces - it will output HTML, PDF, LaTeX etc. format documentation.
IDL is certainly a good idea for a reference. But I guess you'll want to provide code examples and snippets.
Here are a few thoughts:
What kind of COM interface does it expose? IDispatch, custom, dual? You probably made this decision by guessing who your SDK audience is, hence what language they use.
Should you use only one language? Maybe you can provide some examples in C++, some in VB6, some in .NET (either VB or C#).
Choose the language for one given example based on the difficulty (or lack thereof) to use the specific type of arguments in that language.