Documentation and getting the most of the available information
Author: Alexander Stoyan
Platform: Visual C++, Visual Basic 6.0, Visual C#, Visual Basic .NET
Codejock’s business practice has always been to keep up with fixing and improving existing functionality and adding new features in order to remain competitive. While documentation is certainly an important part of it, there are always reasonable limits to which it can be produced. The purpose of this article is to provide answers to common related questions as Codejock frequently receives requests for detailed tutorials, walkthroughs, documentation for various use cases and complains about inability to find the needed functionality.
Given the combined amount of ToolkitPro and SuitePro components, controls, classes, interfaces and environements they can be instantiated in and used from, it is not only impossible to produce tutorials and walkthroughs for all, and especially narrow, use cases, it is impossible even to imagine and count those use cases. Also providing such a comprehensive documentation comes at a price of a very expensive maintenance and keeping it up to date. Shifting focus from improving and development to producing detailed documentation would inevitably result in reducing, or even halting, most future functional updates.
In attempt to solve this dillema Codejock came up with these basic principles to help users get familiar and start working with Codejock technologies faster:
- The code and its public interface must be self-descriptive and easy to read - developers are assumed to be fluent in their programming language and thus be able to read API interfaces and sample code.
- The public interface of a library must contain documentation comments that explain general purpose and unobvious side-effects if there are any. Those comments are used for generating the reference documentation.
- One simple working sample can tell a developer much more than a long tutorial that explains the same code in human words, but a tutorial cannot be tried, debugged or experimented with.
Similar principles are used being by the most open source libraries, so it's a proven approach. As a result we always recommend users to refer to our samples, follow common use cases demonstrated in the samples, use them as their starting point for new projects, test ideas, verify assumptions, modify as needed, debug and report issues, all using our or custom derived samples.
Here are some hints on how to gets the most from the available information:
- Search for related keywords or post a question in our community Forum.
- Search for related keywords in local help files (C:\Program Files (x86)\Codejock Software\MFC\Xtreme ToolkitPro vXX.X.X\Help and C:\Program Files (x86)\Codejock Software\ActiveX\Xtreme SuitePro ActiveX vXX.X.X).
- Check our Release Notes as some changes may have attached links to the associated articles if a change or addition requires special instructions or explanations.
- Check our FAQ articles for the related topics.
For ToolkitPro users:
- Start with exploring samples for a related component in C:\Program Files (x86)\Codejock Software\MFC\Xtreme ToolkitPro vXX.X.X\Samples.
- If you're looking for a correct way of using a method or a class consider plain case insensitive text search amongst all file types in C:\Program Files (x86)\Codejock Software\MFC\Xtreme ToolkitPro vXX.X.X\Samples and C:\Program Files (x86)\Codejock Software\MFC\Xtreme ToolkitPro vXX.X.X\Source, check every found entry accurately and read the code around it to make sure the demonstrated use case is what you're looking for.
For SuitePro users:
- Refer to the official documentation for your development environment and language in order to learn how to host ActiveX controls and deal with the related concerns.
- Refer to the community and official resources for your development environment and language for all integration related questions that fall beyond the scope of API exposed by .OCX components from C:\Program Files (x86)\Codejock Software\ActiveX\Xtreme SuitePro ActiveX vXX.X.X\Bin as various development environments can generate automatic wrappers for hosted ActiveX components and perform caching of control's properties which is frequently a source of different issues and misuses that Codejock is not responsible for.
- If you're looking for a correct way of using a method or a class consider plain case insensitive text search amongst all file types in C:\Program Files (x86)\Codejock Software\MFC\Xtreme SuitePro vXX.X.X\Samples. Check every found entry accurately and read the code around it to make sure the demonstrated use case is what you're looking for.
You can always extract declaration of the entire public ActiveX library interface and use it for quick finding of method and class names, available constants and events, clarification of argument types, etc. Overall this will give you a better picture of API structure than a sparse reference documentation. Some environments generate wrappers that immediately expose their structured API in an easily browseable form, like .NET AxImp:
Users of other environments are not left without options here, one of the easiest and most accessible way to extract the whole ActiveX API definition is to use OleView utility from Microsoft SDK package. Using OleView select File -> View TypeLib... menu item and and select the needed .OCX file from C:\Program Files (x86)\Codejock Software\ActiveX\Xtreme SuitePro ActiveX vXX.X.X\Bin and it will extract all type library infromation from that file regardless whether the module is registered or not, and it will represent it in a simple IDL syntax along with the structure tree:
- If no answers can be found in using the mentioned above steps, users with active subscription are encouraged to Request Support using sample projects or barebone versions of their projects in order to facilitate processing and do not overload our support developers with incomplete or unclear questions. In this case we ask users to respect and follow our Support Policy.