I'd just like to say how disappointed I am with the documentation for Xtreme Toolkit Pro.  If you are going to rely on generating it from header files, you really must check that what's generated is actually helpful.  For example, select this entry in the online help:

  Xtreme Toolkit Pro v 8.61/Classes/CXTResize

Scroll down to the table of methods and look at  the entries for SetResize.  There are 7 of them, 6 of which have almost the same description.  The corresponding description is displayed if you click on any of the entries.  None of the descriptions explain how to use the parameters.  If you select the 6th variant, then follow through by clicking on XT_SIZING, you get the recursive description that "The XT_SIZING structure is a stand alone helper structure class. It is used by the CXTResize class to maintain size and ID for a particular window being sized.".  It would be far better to say "we couldn't be bothered to document this stuff, so look at FlatComboDlg.cpp for clues, and step through with a debugger, if it still doesn't make sense".  At least that would save your customers from wasting their time trying to glean something useful from the documentation!

Other criticisms:

1. There is no list of sample code, stating what features each sample demonstrates.
2. There are very few tutorials: use of resizable dialog boxes is clearly missing.
3. Classes are not categorized by function.
4. There is no introductory material summarizing all the capabilities of the library, with links to the detailed documentation.

I could go on, but I haven't the time.  If you are open to suggestions, sit beside an experienced MFC programmer, who's just starting to use your library, and silently watch them struggle.  Then write the missing documentation.

I've just come across another gem, which I'll share with you:

CXTTabCtrlBaseEx

CXTTabCtrlBaseEx is a mk:@MSITStore:C:\Program%20Files\Codejock%20Software\MFC\ToolkitPro\help\XtremeToolkitPro.chm::/CXTTabCtrlBase.html - CXTTabCtrlBase derived class. It is used to create a CXTTabCtrlBaseEx class object.

It's certainly a concise statement, but not a single word adds any understanding to the purpose of this class, how to use it, nor its advantages over CXTTabCtrlBase (the documentation of which is no better)!

This sort of thing would be acceptable for free software, but when there's a price tag, you expect better.  I've seen much better documentation for free software from CodeProject.  In fact, I was only able to understand how to use CXTResizeDialog after reading this article:

http://www.codeguru.com/Cpp/W-D/dislog/resizabledialogs/article.php/c1925/ - http://www.codeguru.com/Cpp/W-D/dislog/resizabledialogs/arti cle.php/c1925/

I Agree. The XTP Documentaion needs a lot of work.

The Tutorials are good but insufficient. You have to struggle with the sample projects to figure out how to program what you want, and the documentation in the help is far from sufficient. There is no general information for the purpose and the way to use the XTP classes/functions in the docs.

I was initially very frustrated with the documentation. To the point that I sent tons of e-mails and suggestions to the support team. This was in the first week of trying to learn how to apply it to my application.

I also made the same suggestion that samples should be indexed based on features that they use to make finding relevant code easier.

In my app menus and toolbars are completely dynamic and defined via configuration scripts. So none of the standard functions of loading them from existing resources applied. Also, the initialization of these could not be done during window creation as in all the samples because the script engines including VBA are not initialized until some time after the creation of the window. None of the documentation was relevant even at hinting where I should start looking much less provide the relevant information.

However, after the initial frustration and reluctance to dive into the XTP source (headers and source files) I finally did dive into these. What I discovered is that if you are willing and able to work with the source, frustration will diminish enourmously.

The toolkit is well architected and easy reading (as easy as heavily modal, event driven application can be). The added advantage is to be able to single step and break point live code to get a better understanding of how it works.

I also discovered that the functionality I needed to use is way out of the beaten path and was either missing altogher or had some "omissions" or bugs which were easy to fix once I got familiar with the layout of the source files. My version now has some tweaks that allow completly dynamic menus and toolbars which can also be customized. The added functions were quickly built from existing functions as a starting point with a little experimentation.

I no longer refer to the documentation except for very rare circumstances such as finding an Enum that I know is listed there, but not much more. I go directly to the header files and source files to get my answers.

In the end I was able to get all the functionality working in my non-standard app. The re-use of CXTPControl and CXTPControls for all control functions in menus, command bars, popups makes creation and manipulation of these much cleaner that the previous code that dealt directly with Windows versions of the same.

It is unfortunate that the documentation proves such a turn off initially that some user can drop the toolkit altogether before discovering its power and beauty. It is well written and easy to find your way around once its "undocumented" architectural concepts are understood.

However, from my communication with XTP they are very aware of the problem and are actively addressing it. Also in their defense I must also add that as I understood the toolkit breadth and depth better I also saw that documenting the complexity of the toolkit will not be an easy task and will take a lot of iterative effort.

I can't agree with you about the benefits of reading the headers, rather than the documentation, because the latter is created from the former.

As another example of how useless the documentation is, I wanted a menubar with command bitmaps that match the equivalent toolbar commands.  I missed the relevant entry in the contents, because there was nothing obvious starting with CXTMenu, but subsequently discovered a whole bunch of classes starting with CXTP (the reason for which is not documented), including CXTPMenuBar.  Does it do what I want?  Who can tell, from a description like this: "CXTPMenuBar is a CXTPToolBar derived class".  What is the point of that?

It's really not that difficult to write useful documentation.  You just have to ask yourself what the reader needs to know, and write the answers.  In this case, the obvious requirements are:

1. What will this class do for me?
2. How do I implement it in my application?

The nitty gritty may be obtained from the header files, but I'm only inclined to read them if I'm already confident that the class has the capabilities I need!

Calvi,

Everyone agrees with you, he is just trying to help you out.  This has been discussed at length before.  Be thankful you started with the version you did :)

They are making progress bit by bit.

edit: idiots like me need a lot more hand-holding than average, so Im sure I backed up plenty of their mail folders in the past :)

Blah-blah-blah.

Blah-blah-blah.

CXTTabCtrlBaseEx

CXTTabCtrlBaseEx is a mk:@MSITStore:C:%5CProgram%20Files%5CCodejock%20Software%5CMFC%5CToolkitPro%5Chelp%5CXtremeToolkitPro.chm::/CXTTabCtrlBase.html - CXTTabCtrlBase derived class. It is used to create a CXTTabCtrlBaseEx class object.

Blah-blah-blah.

I have to agree with Andrei, the source code is the best documentation you can get. I didn't use the help file in any way, the source code and the class layout are well designed. I spent some time with the debugger and tried to understand the working model of the Toolkit.

At the beginning (I used another library before) I had some questions how I can achieve some things with the Toolkit and all my support calls (via eMail) are answered.

Blah-blah-blah.

arc42,

You're the most stupid asshole I've ever met. If only I could get at you I'd beat all sh*t outa you, son of a bitch.