*&* CLASSDOC
*&* to document class hierarchies
*&* >L< Lisa Slater Nicholls
*&* Revised November 1997

The following files are contained in CLASSADD.ZIP:

  Name                Comments 
  ----                --------
 CLASSDOC  TXT        This file
 CLASSDOC  PRG        The utility itself
 CLASSADD  PRG        A sample add-on for CLASSDOC

This file has several sections:

1) How to use CLASSDOC in its present state

2) Preference-setting in CLASSDOC

3) Other stuff that may happen to the CLASSDOC classes in the future

4) What to do to cleanup in event of a crash (don't worry, nothing 
   dangerous is going on <s>)! 
   
1) How to Use CLASSDOC
======================

CLASSDOC.PRG has three main parts.  They are really only in one file 
for convenience, so that you have everything you need to run in one file:

* part 1 is the #DEFINEs, which ordinarily would be an .H #INCLUDE file;

* part 2 is the sample program which instantiates the CLASSDOC class of 
your choice and gets results;

* part 3 is the class definitions, which could easily be in a VCX file 
and ordinarily would be.

Here are the params you can pass to the sample program (part 2) :

 tcClassDocClass,  ;   && which classdoc class/what output do you want?
 tcBaseClassLib,  ;    && your base class library
 tcPrimaryTextTarget, ;&& where full class doc will be written
 tcAddOn               && PRG to add functionality to your chosen class

All these params are optional and they are all matched by #DEFINEs
in part 1... 

 #DEFINE DOC_PREFERENCE_CLASS         
 #DEFINE DOC_PREFERENCE_BASECLASS_VCX 
 #DEFINE DOC_PREFERENCE_PRIMARY_TEXTTARGET 
 #DEFINE DOC_PREFERENCE_ADDON              

... so you can set them up to match your standard requirements,
*without* passing any params.

Here's what the parameters do:

The first param tells the sample program what class to 
instantiate, and the other three are passed on to the class.  

So that you can try the various classes available, the sample 
program has a procedure GetClass() to bring up a popup telling you 
what they are and approximately what they do. The sample program
brings up this popup if you don't pass the first parameter, 
regardless of the contents of the #DEFINEd DOC_PREFERENCE_CLASS.  

If you continue to use this sample program and don't need the 
popup (either because you change DOC_PREFERENCE_CLASS to your 
constant choice or because you feel comfortable passing the 
actual class name as a param to the program), simply comment 
out the block of code in PROCEDURE GetClass() where indicated.

The various classes in the current CLASSDOC tree allow you 
to get the following results:

1) DOCFORM -- a textfile which includes full documentation (class code)
for all investigated classes that descend from your base class library
classes.

2) SUMMARYDOCFORM -- the textfile above, plus a MODI MEMO of the 
classnames only.

3) CLASSMEMBERDOCFORM -- the MODI MEMO has classnames plus 
properties/method names added at each class level.

4) VISUALDOCFORM -- a Treeview of the classes you'd get in 
#2 above, which when doubleclicked takes you to the 
appropriate position in the full documentation text file as 
described in #1 above

5) VISUALCLASSMEMBERDOCFORM -- a Treeview of the classes 
you'd get in #2 above, which when doubleclicked takes you 
to the appropriate position in the text contents you get in 
#3 above.

That covers the first param (available classes)! 

The second parameter overrides your #DEFINEd preference for
the VCX you designate as "base". (CLASSDOC is going to ask you
to locate this VCX if it can't find it without your help, of
course, no matter how you designate it.)

CLASSDOC automatically investigates all the VCXs in the 
directory containing the VCX you designate as "base".  
However, it also gives you a chance to designate other 
directories you want to include. If you don't need any 
other directories, just press cancel when asked to designate 
them.  I have not yet included the ability to *eliminate* 
VCXs from the list of possible VCXs that eventuates from 
the chosen directories, but IMHO this is really not crucial! 

The third parameter sets the text filename that holds full
documentation, created in the base CLASSDOC class and providing
the basis for all the output in other classes. You'll want to
use a location with plenty of space, since this file can be large.
When you subclass CLASSDOC yourself, you'll be able to parse 
this file to provide any kinds of output you desire (such as
Inserting any subset of it, in appropriate formatting, into
a Word document).

This part of CLASSDOC (designating VCX and text filenames) 
uses the common dialog OCX when appropriate.  If there is a 
failure of the common dialog OCX for any reason, the CLASSDOC 
classes will use a FoxPro GetFile() dialog to perform the same 
task. If you know you are on a laptop without full installation 
of OCXs, you can change a #DEFINE (DOC_OMIT_TRYING_OCXS) so 
that it doesn't even bother to attempt the common dialog. 
(There is appropriate errorchecking in the classes that use 
the Treeview control to handle the same sort of problem.)

The fourth param allows you to massage the examined class 
records in additional ways. I've written CLASSADD.PRG as a very 
brief example of what you might do to write add-ons to these classes. 
There are some notes in CLASSADD.PRG, and the DocForm.RunAddOn() 
method also contains some useful comments.

2) Preference-setting and additional #DEFINEs
=============================================

The #DEFINE/Header section of CLASSDOC.PRG is further
broken down into several sections, as follows:

* -- preferences, settable/overridable from the params for a 
given run, already described above

* -- additional (non-param) preferences to match the way you work, 
like DOC_OMIT_TRYING_OCXs.  You may want to review this group of
#DEFINEs to see if you want to change any of them, but after the
first time you probably will leave them alone.

* -- required constants follow here, none of which you should 
need to change

Each #DEFINE has its own comments, which I think will be sufficient.

3) Further development
====================== 

Even before I think about more elaborate dialog presentations, 
lots more can be done with the visual components even within
the treeview-centered forms already available in this class tree.

For example, I would suggest adding an imagelist control that 
provided a picture for each of the baseclass controls allowed by 
Fox.  For efficiency I would just put this on the top level class lines.

Another sample program to instantiate the classdoc form might have 
a "preference" form preceding the instantiation of the classdoc object,
so that, instead of my various rudimentary GetDir()s and so on,
you'd have a chance to choose your output format and target filename(s), 
classdoc class to instantiate, possible addon functions, baseclass.vcx, etc,
in a single form. You could keep the parameters in the current sample 
call, but make alternatives easier to choose.
	
Right now, the full class documentation always goes to a text file 
(the "primary text target"), which remains on disk, while the 
summary information, if you've asked for any, appears in a MODI MEMO 
suitable for copying and pasting to a notepad file.  The classes that
use the treeview for displaying classes will "expand" into
various levels of detail when you double-click a line.

However, all the classes that need summary information create a 
temporary text file (the "secondary text target") as a necessary 
intermediate step, so you could decide to make the summary 
information persistent very easily.

I'd like to enhance CLASSDOC to allow VCXs in the chosen directories 
to be omitted. Any classes within these VCXs that are not descended 
from the baseclass.vcx set of classes will be omitted anyway, of 
course.  (In fact CLASSADD.PRG, the sample addon, counts the number 
of such classes that exist with the VCXs examined, just to make this point.)
	
I intend eventually to create the output using separate collaborating 
output classes, so they can be switched from the current TEXTMERGE to 
create Word documents, and other formats.  This change is worth doing well, 
which means that the output classes I'm talking about should have nothing
to do with CLASSDOC and tons of other uses. *THAT* means it's going to 
take a lot of time and I won't get it done for a while.  

4) What to do to cleanup in event of a crash 
============================================

If you have had a GFP while editing a VCX, it's possible to have corrupted
records in your VCX table that purport to describe normal classes but have
no objname contents.  This won't hurt you for any other Fox uses of the VCX,
since you'll just never see those records. However, CLASSDOC goes from the
objname of your libraries to hunt for descendents of each class -- so an 
empty objname will cause some endless recursion.

You will realise this when :

-- you run out of program stack levels

-- classdoc terminates abnormally as a result.

At this point you should have at least one text file (the main one, 
full docs, whose name you indicated) on your disk.  Depending on which
CLASSDOC class you're using, you may have another one.  The second
one will be in your getenv("temp") directory and have a TMP extension. 

There may also be temporary working files from classdoc's cursors --  
you will want to clean these up as with any other crashed VFP program!

You can safely delete both temporary text files, along with Fox's working
TMP files from the cursors.  However, before you do, *EXAMINE THE BOTTOM* 
of one of them (use MODI COMM).  You will see lots of empty space.  

Go back to the *last text* showing in the text file. This last class 
entry will say something like "class <vcxfilename>! ".  Notice the 
empty space after the delimiter. IOW, this entry should give you a 
clue as to what VCX has the corrupted record.  Browse this file
and figure it out! You should be able to clean up your VCX and re-run
CLASSDOC.