In article <summer.755215801@mullian.ee.Mu.OZ.AU> summer@ee.mu.OZ.AU (Mark Summerfield) writes:
> What you really want are tools that allow you to browse through classes,
> print them etc., but which only show you the relevant information.  For
> example, a text-based tool might list for you, in some sensible format,
> only the public members of a class.  If it was a little smart it might
> be able to extract any comments describing the purpose and effect of any
> member functions, without actually displaying any of the implementation
> details.  This kind of tool would work a little like the man page system
> under Unix: its output could be generated on the fly from on-line source
> code, or it could be pre-compiled which would perhaps save time, and the
> need for keeping source (particularly useful for commercial libraries
> which you may not have complete source for).
>
> I'm sure that such tools must exist for some commercial C++ packages, but
> does a generic tool of this kind exist which runs under Unix?

Try DocClass, a tool I wrote which does just this sort of thing. Here is
the standard blurb ...

Docclass is a simple C++ program which reads in C++ header files, and
outputs documentation describing the class hierarchy, methods, inherited
methods etc.

All output is now through an OutputProcessor class, which can be
subclassed if you want fancy printer output.

Docclass has a rather dumb parser, but it should cope with reasonably
sane C++ class declarations. It understands comments, and tries to group
the comments with the appropriate class or method.

Docclass does not require templates, or nested classes, as many people have
C++ compilers which don't support them. With any luck, it should
understand them a little in the code it analyses, though.

Docclass has been compiled under Zortech C++ 3.0r4, Borland C++ and
GNU gcc 1.4.5.

Docclass is Copyright (c) Trumphurst Ltd. I have made it available on the
Internet for personal use only. Please do not use it in a commercial
situation (except for testing to see if it is suitable) without first
obtaining permission (mail address below).

It is available for public ftp from
 ftp.demon.co.uk:/pub/trumphurst/docclass.zip.

Comments, improvements etc. should be emailed to
 docclass@trmphrst.demon.co.uk

Trumphurst Ltd. reserve the right to remove the program from public
distribution at any time.

Please note that I originally called this program "classdoc", but that
name conflicts with the classdoc package written by dag@control.lth.se
(Dag Bruck). His package, written in AWK, produces UNIX-style manual pages
from C++ class headers. If you are interested in automatic documentation,
you might want to look at this too.

--
Nikki Locke,Trumphurst Ltd.(PC and Unix consultancy) nikki@trmphrst.demon.co.uk
trmphrst.demon.co.uk is NOT affiliated with ANY other sites at demon.co.uk.

kbennett@access.digex.net (Keith R. Bennett) writes:

>One of the goals of object oriented programming, as I understand it,
>is to separate the interface from the implementation of a logical
>object.  Thus, the class' header is distributed to users of the
>class, but the implementation can be hidden by distributing a library
>(or object) file, but withholding the source code.

>This being the case, why are private data and function members
>included in the class header?  It would seem to be more consistent
>with the OO philosophy to put them somewhere else, in the
>implementation (.C or .CPP) file perhaps, where the user of the class
>could not see them.

Are there any C++ documentation tools?  When I used the Eiffel system
back a few years ago, it had this feature.

What you really want are tools that allow you to browse through classes,
print them etc., but which only show you the relevant information.  For
example, a text-based tool might list for you, in some sensible format,
only the public members of a class.  If it was a little smart it might
be able to extract any comments describing the purpose and effect of any
member functions, without actually displaying any of the implementation
details.  This kind of tool would work a little like the man page system
under Unix: its output could be generated on the fly from on-line source
code, or it could be pre-compiled which would perhaps save time, and the
need for keeping source (particularly useful for commercial libraries
which you may not have complete source for).

I'm sure that such tools must exist for some commercial C++ packages, but
does a generic tool of this kind exist which runs under Unix?

Mark.
          --------------------------------------------------------
              Mark Summerfield,  Photonics Research Laboratory
Department of Electrical and Electronic Engineering, University of Melbourne
                ACSnet[AARN/Internet]: summer@ee.mu.oz[.au]
          --------------------------------------------------------

>>>>> "Mark" == Mark Summerfield <summer@ee.mu.OZ.AU> writes:
In article <summer.755215801@mullian.ee.Mu.OZ.AU> summer@ee.mu.OZ.AU (Mark Summerfield) writes:

Mark> kbennett@access.digex.net (Keith R. Bennett) writes:
Keith> One of the goals of object oriented programming, as I
Keith> understand it, is to separate the interface from the
Keith> implementation of a logical object.  Thus, the class' header is
Keith> distributed to users of the class, but the implementation can
Keith> be hidden by distributing a library (or object) file, but
Keith> withholding the source code.

But the interface / implementation limit has no reason to pass by the
header file / source file limit.

For a start, there is no *one* priviledged interface to any real
logical class. The header file is only a suitable interface for the
compiler to perform adequately checking about the legibility of use of
the class.

Keith> This being the case, why are private data and function members
Keith> included in the class header?  It would seem to be more
Keith> consistent with the OO philosophy to put them somewhere else,
Keith> in the implementation (.C or .CPP) file perhaps, where the user
Keith> of the class could not see them.

But there may be friends, and private members are part of their
interface.

Mark> Are there any C++ documentation tools?  When I used the Eiffel
Mark> system back a few years ago, it had this feature.

[ ... ]

Mark> If it was a little smart it might be able to extract any
Mark> comments describing the purpose and effect of any member
Mark> functions, without actually displaying any of the implementation
Mark> details.

[ ... ]

Quoting Meyer: a fundamental principle of software design: avoid
documentation.

Such documentation is only a compromise, the testimony of a failure to
put the information under a more formal, i.e. tool checkable, format.

--
+-----------------------------------------------------------------------------+
| Marc Girod - Nokia Telecommunications       Phone: +358-0-511 7703          |
| TL4E - P.O. Box 12                            Fax: +358-0-511 7432          |
| SF-02611 Espoo 61 - Finland              Internet: marc.girod@ntc.nokia.com |
|    X.400: C=FI, A=Elisa, P=Nokia Telecom, UNIT=TRS, SUR=Girod, GIV=Marc     |
+-----------------------------------------------------------------------------+