Re: ActiveX documentation

["Wing, Michael J" <mjwing -at- INGR -dot- COM>]

Jean;

My suggestions on documenting ActiveX controls are as follows:

-- Cite the name of the OCX/Oca control (both the title as it appears in the
references list and the file name) in the help (especially in any example
code descriptions).  This reduces the frustration by programmers when the
control does not appear in the references and must be registered manually.

-- When describing the ActiveX control object, summarize the characteristics
and functions that can be programmed through the object.  For example, a
Directory Tree control may provide automation for collapsing directories,
assigning drive letters, moving directories, renaming directories and so
forth.

-- Make sure that all property topics specify if the property is read-only,
read-write, or write-only.  Also specify the property type (Long, Variant,
and so forth), default values, and whether the property accepts NULLs.

-- Make sure that method topics have the following information:
   - A return data type (depending if the method is a subroutine or a
function)
   - Whether arguments are input, output, or input/output arguments
   - Whether arguments are required, optional, required only if another
argument is
      used, or omitted if another argument(s) is used
   - The data type for each argument
   - Whether the method should be run once, multiple times, and whether then
     method should be run in a particular place in a sequence (workflow).

-- Make sure event arguments have the same information as method arguments.
Some events are self-explanatory as to when they fire (such as a click
event).  However, some are not (such as setMarker).  Make sure the reader
knows under what circumstances the event fires.

-- Explain any interactions between properties and methods.  For example,
does the setting of a method's argument reset a property value?  Can a
certain property be set after running a particular method?

-- Make sure that the examples work!  My experience is that the reader cuts
and pastes them and tries to run them before even reading the topic.

-- Describe any requirements: OpSys minimum/restrictions.  Must have VB5.0
or higher, requires strong typing for Delphi, only works in Internet
Explorer, etc...

-- If the ActiveX control can be imbedded and programmed using DHTML,
describe the procedure for making automation elements available (which
<Param> tags need to be placed within the <Object> tags).  Are there
additional requirements to allow the control to work in Netscape?

-- Use a browser that does not expose hidden automation to determine what is
available from programming.  An added benefit is a browser that shows the
assigned helpcontextids and help file.

I haven't tried autoDuck for 3 years.  As I remember it was dependent on the
programmers comments in the code.  That's scary. Instead, I have written
word macros that extract information from a text file (generated through
OLE2View.exe) and create/link help topics.

Mike

Michael Wing (mailto:mjwing -at- ingr -dot- com)
Staff Writer
Intergraph Corporation; Huntsville, Alabama
http://maps.intergraph.com


> We are in the process of designing documentation for a
> set of ActiveX controls.  The documentation, for programmers, will
> be delivered as WinHelp files (including context-sensitive Help).
>
> Does anyone have any general advice for documenting ActiveX controls?
>
> Has anyone used Autoduck or other automated processes to generate ActiveX
> documentation?
>
> Thanks in advance.
>
> Jean Blakeman
> jblakeman -at- aai -dot- com
>
> Amerinex Applied Imaging, Inc.
> Northampton, MA
> 413-592-9600
>
> From ??? -at- ??? Sun Jan 00 00:00:00 0000=
> =
>
>

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=