zikacj - DLL help file option for programmer's who forget - like me?

Hi,

I'm using VC++ V4.0 on Windows 95 and NT 3.51/4.0

I write a number of DLL's and would like to be able to call the DLL and retrieve
documentation from it (which I'll provide).

I'd like to here your comments and suggestions!

Here's my plan so far: the DLL is called ABC.DLL
(1) Call a function long DOCABC(char s[],char function,long detailtype ,long maxlen);

(2) The text documentation is returned in s[] and the length of the returned string is the return value of
the function DOCABC. The maximum length is suplied by the user so the buffer doesn't overrun.
The detailtype is either 0=full, 1=interface only, 2=short description 3=long description

If the user supplies a function name only documentation for that function is returned.

A few things supl;ied in the docs might be
(1) Visual Basis and Visual C++ parameter/argument description and examples,
(2) A short text description
(3) A long description
(3.1)describing inputs and outputs in detail
(3.2) User considerations
(3.3) error handling
(3.4) Options
(3.5) Performance considerations
(3.6) program ussage

If a typical DLL has between 30 and 200 functions and I limit
the documentation 500 chars for each function and put the documentation
in a seperate text file its size would be 15K to 100K (uncompressed).

I've seen a lot of internal documentation and audit trails in people writing things
like UNIX Operating systems, and software utilities and diagnostics that
a large number of technicians and engineers must look at to understand their
work. I find some simple examples and a text with a lot of white space
and perhaps character based (courier font) graphics help a use the most.
Audit trails and inconsistent format of docuementation makes comprehension of the
material a challenge. On the otherhand good formatting without examples and graphics
can often be useless.

As programmers, what would you like to see in documentation for simple DLL functions?

The functions I write are text filters, math operations, and general purpose tools for full-text
searching and indexing large databases.

all comments are greatly appreciated,

I'd like to do this right!,

- Chris ([email protected])

There are several tools for extracting documentation from code already.
Autoduck from MSDN is one I use. It will generate rtf files from source
code comments so you can generate an .hlp for "on-line" help. There is
a utility called rtf2html that can convert that to html. Or, I think autoduck
can generate html from source and I think there are others tools that can.
I have set up a makefile that can generate a help file from my stuff and
it works really well. One command and presto, instant help file.

By the way, you might want to consider upgrading to VC++ v5.0.
They made numerous improvements. From what I understand,
the jump from 4.0 to 5.0 was bigger than from 5.0 to v6.0. I use v5.0
and will not be going to 6.0 anytime soon. I have heard far too many
horror stories.