RE: documenting a TLB file

[Dubey Akash <Akash -dot- Dubey -at- sisl -dot- co -dot- in>]

Hi Colleen,

As per my understanding, you want to provide information on all the methods
enclosed in TLB. Please correct me if I'm wrong. Moreover, you also want to
display the appropriate help topic while a programmer is coding in Visual
Basic, and hits F1 after placing the cursor within the method name (i.e.
context-sensitive help).

We have implemented the same functionality for all the DLLs (created by
compiling IDL) of our product's Architecture. FYI, A type library is a
binary version of an Interface Definition Language (IDL) file. It contains a
binary description of the interfaces exposed by a component.

The programmers in our organization compile IDL (Interface Definition
Language) file to generate DLL. This compilation also generates the
corresponding TLB file automatically. If same technique is followed in your
organization, then perform the following steps to provide context-sensitive
help for all the methods enclosed in the DLL (TLB).

1. Include the "helpfile" attribute in the attribute's block preceding the
"library" block. Refer to the following example.

[
        uuid(221779B4-3B6C-11D4-94DD-00B0D02D8DB8),
        version(1.0),
        helpstring("TestClass 1.0 Type Library"),
        helpfile("...Dir Path...\Test_Online_Reference.chm")
]

library HPERSISTENCELib
{
importlib("stdole32.tlb");
importlib("stdole2.tlb");
//...
//...
}

2. Include the "helpcontext" attribute in the attribute's block preceding
the "interface" block. Refer to the following example.

[
object,
uuid(7D5686E3-9CDD-46F0-92B2-B39B71205319),
dual,
helpstring("IHPersistent Interface"),
helpcontext(<unique_no>),
pointer_default(unique)
]

interface ITest : IDispatch
{
        //...
};

3. Include the "helpcontext" attribute before the method name. Refer to the
following example.

interface ITest : IUnknown
{
[helpstring("method Test"), helpcontext(<unique_no>)] HRESULT  Test([in]
param1, [in] param2, [out, retval] param3);
};

4. Add the same map IDs (unique no) to the corresponding topics in your
'.chm' file.


For queries, if any, feel free to drop as many lines as you want :-)

Regards,
Akash

**************************************************************
Technical Writer
Siemens Information Systems Limited
India.



-----Original Message-----
From: Colleen Strahs [mailto:colleen -dot- strahs -at- divine -dot- com]
Sent: Tuesday, July 09, 2002 3:28 AM
To: TECHWR-L
Subject: documenting a TLB file



Hello Tech Writers:

I am about to begin documenting a type library. It's a TLB file that our
programmers have generated, to be used to create custom ActiveX objects
that work with our product. Customers may write their ActiveX objects in
Visual Basic or Delphi.

I'm an experienced API tech writer but I have dealt exclusively with
Java until now. I would like to create an online reference for the API
contained in the file, similar to Javadoc output. My understanding from
my developers is that the TLB file is created automatically. I don't
have access to a source file, like I do with our Java APIs. And there is
apparently no way to embed code comments (ala Javadoc) into the TLB
file, which is binary. Please correct me if I'm wrong.

An online search located one tool (Document! X:
http://www.vbhtmlhelp.co.uk/products/documentx.asp) that seems to do
pretty much what I want. But alas, we have literally no money to buy
tools right now. I do have a copy of doxygen, but I'm not sure if it
will do what I want. If I don't have specific source files that I can
enter comments in, should I just write up my documentation in a text
file and process it through doxygen?

What about facilitating context-sensitive help from within the IDE? Does
anyone do that? How? (such that when you select a method and hit F1, you
get help about the method)

Am I missing something big here? Note that this API is fairly small.
Doing the API reference by hand won't kill me, but I was trying to find
a way to neatly generate some kind of standard output, automate the
cross-references, facilitate maintenance, etc. 

Thanks!
--Colleen Strahs


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Save $600: Create great-looking Help files and software demos with
RoboHelp Deluxe. Get RoboHelp and RoboDemo - our new demo software - for one
low price. OR Save $100 on RoboHelp Office in June with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit http://www.raycomm.com/techwhirl/ for more resources and info.