zikacj
April 8th, 1999, 10:39 AM
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 (zikacj@aol.com)
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 (zikacj@aol.com)