home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The World of Computer Software
/
World_Of_Computer_Software-02-385-Vol-1of3.iso
/
d
/
doc301.zip
/
CHANGES.301
next >
Wrap
Text File
|
1992-12-15
|
18KB
|
400 lines
DOC Version 3.01
------- Overview of DOC's Design Philosophy --------
In order to understand why DOC works the way it does it would be
helpful to know how I view DOC and how I intended that it be
used. DOC assumes that a Clipper programmer wants to thoroughly
document each function with comments in the source code. DOC also
assumes that the programmer desires that these comments should
immediately precede the function, that they should be in a
standard format and that the programmer should only have to
document a function once, changing his/her comments only when and
as much as the function changes. DOC assists the programmer in
accomplishing these goals by allowing the programmer to design
the function comment header's appearance, creating the header in
the source code when it does not exist, filling in all the
information that it can glean from the source code, and
preserving the programmer's inserted comments when they exist.
DOC also assists the programmer by creating function reports and
a Norton Guide database from these headers comments, multiplying
the programmer's efforts to document his/her source code.
DOC can be used without typing comments into the function
headers. DOC will even create a Norton Guide database from source
code without function header comments, although it will be a
minimum sort of documentation -- all the functions will be lumped
into one list, with only the function name, its calling syntax
and its parameters detailed. However, to use all that DOC has to
offer the user should run the source code through DOC a number of
times, filling in the function headers with comments after DOC
creates them, and changing the header comments when the function
is modified. If the programmer does this and keeps rerunning DOC
periodically as the source code is developed DOC can provide
useful and up-to-date documention in headers in the source code,
helpful indenting and capitalization and de-capitalization to
make the source code easier to follow, source code print-outs
with line numbering, page numbering and a Table of Contents,
useful reports such as a Cross-Reference, Database/Index, Index
and Function reports and an on-line database to save the
programmer time and effort during programming.
---------------------------------------------------------------------
NEW FEATURES THIS VERSION
1. Cross Reference and STATS reports.
2. User configuration of Function headers.
3. Improved Norton Guide database creation, including user configuration
of the NG menu structure and See Also : support.
4. Database path seperate from Source Code path.
5. Command line parameters for running DOC from batch or make files.
This READ.ME file documents all the changes between DOC version
2.12 and 3.01. If you have used and are familiar with DOC 2.12
you should only need to read this file to get up to speed with
version 3.01. If you have not used previous versions of DOC you
should read the User's Manual.
Note : If you have configuration files (these are files in the
Source Code directory named CONFIG.DOC unless you supplied a
different name) created by previous versions of DOC you must
delete them before running Version 3.01. The number of new
variables which DOC now writes to the configuration file made it
impossible to allow DOC to read the files created by previous
versions.
---------- Command Line Parameters -------------
These were added to allow DOC to be called from a batch or make
file for unattended operation. This can only be done after DOC
has been run at least once interactively for a particular
programming project, the user has typed in all the information
and selected the desired configuration in the menus and saved the
configuration to a configuration file. Once the configuration is
set so that the user only needs to type in the Source Code path
(if it is not the default DOS directory) and the Configuration
File Name (if it is not CONFIG.DOC) and then tell DOC to Go then
the user is ready run DOC unattended using the Command Line
Parameters.
-S<path> Sets the Source Code Path (the directory containing
the configuration file and the make file). If the DOS default
directory is set to the Source Code Path before DOC is run this
is not needed.
-C<file name> Sets the Configuration File name to something other
than the default CONFIG.DOC. If several programming
projects share a source code directory only one of them can use
the default name of CONFIG.DOC for its configuration file and the
others must specify a different name whenever DOC is started.
-G Causes DOC to skip the menus and start documenting.
FOR EXAMPLE :
The following line in a batch file:
DOC -sD:\CLIPPER5\SOURCE\MYAPP -cMYAPP.CFG -g
would run DOC unattended assuming there was a DOC configuration
file named MYAPP.CFG in the directory D:\CLIPPER5\SOURCE\MYAPP.
The following lines in a batch file:
D:
CD \CLIPPER5\SOURCE\MYAPP
DOC -G
would run DOC unattended assuming there was a DOC configuration
file named CONFIG.DOC in directory D:\CLIPPER5\SOURCE\MYAPP.
---------- Cross Reference Listing ----------
DOC can now create a cross reference listing. The only options,
selected in the Report Output Screen, are whether or not to
create the listing (which does lengthen DOC's processing time and
increases the size of the temporary databases significantly) and
whether or not to include key file function names in the listing.
---------- Stats Report ----------------
This is a report, which DOC will from now on always create, which
lists the number of lines of code, number of lines of headers and
number of lines total and number of functions for each source
file documented and totals for the entire application. It is a
small report which does not add noticeably to DOC's processing
time or temporary file size.
------ Function Header Configuration -------------
Two new input screens have been added in the "Output" section -
Function Headers and Norton Guide Creation.
The Function Headers input screen looks like this:
Enter Function Header Options
(Read) Purpose Heading " Purpose :"
(Write) Purpose Heading " Purpose :"
(Read) Out Heading " Out :"
(Write) Out Heading " Out :"
(Read) Comment 1 Heading " Assumes :"
(Write) Comment 1 Heading " Assumes :"
(Read) Comment 2 Heading " Author :"
(Write) Comment 2 Heading " Author :"
(Read) See Also Heading " See Also :"
(Write) See Also Heading " See Also :"
(Read) Ngo File Heading " NgoFile :"
(Write) Ngo File Heading " NgoFile :"
(Read) First Header line "*!*********************"
(Write) First Header line "*!*************************************"
(Read) Last Header line "*!*********************"
(Write) Last Header line "*!*************************************"
(Read) Header left edge "*! "
(Write) Header left edge "*! "
Blank lines between sections "Y"
The default answers correspond to the style headers previous
versions of DOC created.
The (Read) variables are used when DOC is extracting
programmer comments from the code it is reading. The (Write)
variables determine how the headers look in the output code,
action diagrams, function reports and Norton Guides. Therefore,
if you have programmer comments in DOC created headers that you
want to retain you need to set the (Read) variables the way the
matching (Write) variables were set the last time DOC was run.
For example, if you wish your headers to look like this :
/* -------------------------
| Function Main
| Calls : MyFunc()
| : MyFunc2()
| Overview : This is the main menu routine Sets defaults.
| Sets screen color defaults based on ISCOLOR()
| unless given a B/W command line parameter.
| In : Param1 - first command line parameter.
| : Param2 - second command line parameter.
| Returns : Nothing
| Comments : Expects MYDATA.DBF to be in the default directory.
-------------------------- */
and the code contains these comments in a header created by a
previous version of DOC you would set the variables like this:
(Read) Purpose Heading " Purpose :"
(Write) Purpose Heading " Overview :"
(Read) Out Heading " Out :"
(Write) Out Heading " Returns :"
(Read) Comment 1 Heading " Assumes :"
(Write) Comment 1 Heading " Comments :"
(Read) Comment 2 Heading " :"
(Write) Comment 2 Heading " :"
(Read) See Also Heading " :"
(Write) See Also Heading " :"
(Read) Ngo File Heading " :"
(Write) Ngo File Heading " :"
(Read) First Header line "*!************"
(Write) First Header line "/* ---------------------------"
(Read) Last Header line "*!************"
(Write) Last Header line "---------------------------- */"
(Read) Header left edge "*! "
(Write) Header left edge "| "
Blank lines between sections "N"
If the next time you run DOC you have changed your mind and you
want the headers to look like this:
/* =======================
||
|| Function Main
||
|| Calls : MyFunc()
|| : MyFunc2()
||
|| Overview : This is the main menu routine Sets defaults.
|| Sets screen color defaults based on ISCOLOR()
|| unless given a B/W command line parameter.
||
|| In : Param1 - first command line parameter.
|| : Param2 - second command line parameter.
||
|| Returns : Nothing
||
|| Comments : Expects MYDATA.DBF to be in the default directory.
||
============================ */
you would set the variables like this:
(Read) Purpose Heading " Overview :"
(Write) Purpose Heading " Overview :"
(Read) Out Heading " Returns :"
(Write) Out Heading " Returns :"
(Read) Comment 1 Heading " Comments :"
(Write) Comment 1 Heading " Comments :"
(Read) Comment 2 Heading " :"
(Write) Comment 2 Heading " :"
(Read) See Also Heading " :"
(Write) See Also Heading " :"
(Read) Ngo File Heading " :"
(Write) Ngo File Heading " :"
(Read) First Header line "/* -----------"
(Write) First Header line "/* ============================"
(Read) Last Header line "--------------"
(Write) Last Header line "============================ */"
(Read) Header left edge "| "
(Write) Header left edge "|| "
Blank lines between sections "Y"
You must make absolutely sure that no other lines in you code
match the First and Last Header line variables. You also must be
aware that if you do not have the "(Read) Purpose Heading"
variable set correctly, (it does not match the existing headers )
DOC will not find you comments and that if you do not have the
"(Read) Last Header Line" variable set correctly DOC will treat
your entire source code like a comment and not document anything
[this does, however, speed up the processing <g>].
DOC rtrims these variables so spaces on the left are
significant, but spaces on the right are ignored.
--- See Also Heading and NGO File Heading ---
Any programmer's comments placed in See Also and NGO file
sections of the function headers have special meanings to DOC
when it creates the Norton Guide database. If a Norton Guide
database is not to be created then these sections can be retitled
and used for something else, such as "History :" or "Changes :".
If DOC finds one or more function names in the See Also section
of the header it creates a "See Also" or "Related Topics"
reference from that entry to the specified other entries in the
database.
The Ngo File parameter in the headers allows the programmer to
set up multiple function lists and menus in the Norton Guide
database created by DOC. The way it works is if the user wants
the Norton Guide create by DOC to list the functions in multiple
lists selected from a menu rather than the default of all the
functions in one big list then the user needs to do some
planning.
1. Divide up all the functions in the application into a number
of groups.
2. For each group select a menu name and a Ngo File name. The
Ngo File name must be a valid DOS base file name of up to 8
characters.
3. Label each function with the Ngo File name of the group to
which it belongs. This can be done either by typing it into the
function header created by DOC following the Ngo File : prompt or
by by using a NgoFile comment line. You can place NgoFile
comments anywhere in your source code except inside function or
file headers. These comment lines must start with *, // or &&
(not /* ... */ style comments). The first word must be NGOFILE
followed by a valid, up to 8 character, DOS base file name. All
the functions following that line (until the next NgoFile comment
or the end of the source code file) that do not have a group (Ngo
File name) specified in the function header will be assigned to
that function group.
4. When DOC is next run it will create a seperate .NGC (or .EHC)
file for each Ngo File name and will create the lines in the
MAKENG.BAT file to compile them.
5. DOC will also create a link file with a defualt menu
structure. This link file can be used as is, or the programmer
can edit it with a text editor to change the menu wording or
organization if desired before running the MAKENG batch file to
compile and link the Norton Guide database.
For example: if you have put references to the following
NgoFiles in your source code : ARRAY, BROWSE, COLOR, DATABASE,
DISPLAY, DRIVPATH, MENU, PRINTER, STRING and you specfied MISC as
the default NgoFile, you have accepted NGO as the object file
extension, and "My Personal Library" as the Long Name, then DOC
will create the following link file:
!name: My Personal Library
!menu: Functions1
ARRAY ARRAY.NGO
BROWSE BROWSE.NGO
COLOR COLOR.NGO
DATABASE DATABASE.NGO
DISPLAY DISPLAY.NGO
!menu: Functions2
DRIVPATH DRIVPATH.NGO
MENU MENU.NGO
MISC MISC.NGO
PRINTER PRINTER.NGO
STRING STRING.NGO
You must not change the object file names but you can rearrange
the lines, change the !menu: names and the menu names for the
object files. For example you could make the following changes
before running MAKENG.BAT.
!name: My Personal Library
!menu: User Interface
BROWSE BROWSE.NGO
SCREEN_COLOR COLOR.NGO
DISPLAY DISPLAY.NGO
MENU MENU.NGO
!menu: Array & DBF
ARRAY ARRAY.NGO
DATABASE DATABASE.NGO
!menu: DOS, Print & Misc
DRIVE/PATH DRIVPATH.NGO
MISC MISC.NGO
PRINTER PRINTER.NGO
STRING STRING.NGO
-------- Norton Guide Creation Input Screen ----------
The input screen looks like this:
Long Name "My Personal Library "
Norton Guide Short Name "mylib "
Default NGO File "MISC "
Norton Guide Compile File Extension "NGC"
Norton Guide Object File Extension "NGO"
Norton Guide Link File Extension "NGL"
Command to invoke Norton Guide compiler
" NGC "
Command to invoke Norton Guide linker
" NGML "
Norton Guide Long Name - whatever is entered here is written as
the !name parameter in the link file. This is the name of the
Norton Guide Database created from this application. It defaults
to the name of the application as entered in the System Data
menu.
Norton Guide Short Name - this must be a valid DOS base file name
of up to 8 characters. This will be the base file name of the
link file and the *.NG file. It defaults to the base name of the
make file entered in the System Data menu.
Default NGO file - the object file for any functions for which no
NGO file was specified either in the header or by means of a
NGOFile comment. If left blank, functions without a NGO file
specified either through a NGOFILE comment or an entry in the
NgoFile: section of the function header will not be included in
the Norton Guide.
Norton Guide Compile File Extension - if you are using Expert
Help you may wish to change this to "EHC".
Norton Guide Object File Extension - if you are using a version
of the Expert Help linker which expects object files to have an
extension of "EHO" you must enter that here.
Norton Guide Link File Extension - if you are using Expert Help
you may wish to change this to "EHL".
Commands to invoke compiler and linker - if your Norton Guide
Compiler and Linker are not in the DOS default directory or in a
directory in the DOS path you must enter their full path names
here.