COMMENTS - Version 1.1

(c) 1991 by LAMCO Software

The program that will add comments for
you in any of your QuickBASIC listings



What is COMMENTS


Any serious reference manual about programming in any language says at least
once that every programmer should use comments extensively.


Let's face it, that's the part of writting a program that everybody hates the
most.

COMMENTS takes care of a great part of that burden for you by adding to your
listing all the information it can gather from analyzing it.

COMMENTS makes a backup copy of your listing in a file that uses the same
filename with a .BAK extension.

It also creates a separate file with a .STR extension that will contain the
complete structure of your listing if there is at least one procedure.

The new file with a .BAS extension will contain your listing and the
following :

In the Main Module section : For each procedure :

- Name and type - Name and type
- Name of the module (file) - Description
- Language used - Parameters
- Source of the program - All the variables used
- Description - Module level declarations
- Requirements - CONST statements
- Command line parameters - TYPE structures
- Files listed in .MAK file - DECLARE FUNCTION
- All the variables used - DECLARE SUB

COMMENTS doesn't modify your listing in any way. Everything that is added to
your listing by COMMENTS is written inside a box that is added at the very
beginning of the file or over the first line of a procedure (SUB or FUNCTION).


What is added to the module level of your listing


There is one box for each kind of information that COMMENTS can gather from
your listing. The boxes added to the module level will be :

1 - The MAIN box that will contain the Name, Type, Module name, Language,
and Source of your listing.

2 - The DESCRIPTION box contains the description of your program. You
must of course type in that description.

3 - The REQUIREMENTS box. This box will list all that is required by your
program to work properly, that may be for example a CGA or VGA
monitor, or a special Quick Library, or a particular version of DOS.
Anything that is required by your program will be listed here.

4 - The .MAK file box. If you use a .MAK file with your program, the
files listed in that .MAK file will be listed in that box.

5 - The COMMAND LINE PARAMETERS box. If when compiled your program
requires or allows command line parameters, COMMENTS will prompt you
to type in the different parameters that are allowed along with a
short description. You should also write a line describing the syntax
of the command. Everything you will type in when prompted will be
enclosed in this box.

6 - The VARIABLES box. This box will contain a list of all the different
variables and arrays that are used in the module level of your
program. Each variable and array is listed on a separate line so the
next time you load your listing in the QuickBASIC editing
environment, you may add a short description for each of these
variables and arrays.


What is added to each procedure of your listing


1 - The NAME box which tells the name of the procedure and whether it is
a subprogram or a function.

2 - The DESCRIPTION box contains the description of the procedure.
COMMENTS prompts you to type it in whenever a new procedure is
analyzed.

3 - The PARAMETERS box. If any variables, arrays, or TYPE structures are
passed to a procedure through parameters, COMMENTS will identify them
and list them in this box, one to a line, so you may later add a
description to each of them.

4 - The VARIABLES box. Same as in the module level section, but contains,
of course only the variables and arrays used within the concerned
procedure.

5 - Finally, the MODULE LEVEL DECLARATIONS box. This box contains each
declaration that must be made in the module level section of your
listing for the concerned procedure to work properly, except for DIM
statements.

This means that if a TYPE structure is used in the procedure, the
TYPE declaration that is required in the module level will be written
in that box. If a constant is used, a CONST declaration will be
written. And a DECLARE SUB or DECLARE FUNCTION declaration will be
written in that box for each procedure that is called from within the
procedure.

If you should eventually copy the procedure to another of your
listings, you can find out immediately by looking at this box what
are the declarations that you must add to the module level of this
new listing for that procedure to work properly. As for the DIM
statements, look in the PARAMETERS and VARIABLES boxes to find the
arrays used, and then add the propper DIM statements in the module
level or REDIM statements in the procedure itself.

Note : All these boxes are added to your listing, whether they are required
or not. For example, if you do not use any variables in a given
procedure, the VARIABLES box for that procedure will contain a single
line saying "(none)". You may remove these unnecessary boxes if you
wish, but they may be useful since looking at the beginning of a
procedure tells you immediately what is in there and what is not.


Requirements


In order for COMMENTS to work properly, your listings must be written in a
certain way, but as you'll see, you probably already follow these conventions.

1 - The last line of the module level of your listing must be an "END"
statement alone on one line. If you use more than one "END"
statement, replace all of them except the last one by "SYSTEM", or
use another QuickBASIC statement on the same line.

For example, if you make a test that uses an "END" statement, as in
the following case,

IF Level% = 5 THEN
END
ELSE
Level% = Level% + 1
END IF

You can write the same test in any of the following ways :

1 - IF Level% = 5 THEN END ELSE Level% = Level% + 1

2 - IF Level% = 5 THEN
CLS : END
ELSE
Level% = Level% + 1
END IF

3 - IF Level% = 5 THEN Note : CLS has no effect
END : CLS since the program
ELSE will end before
Level% = Level% + 1 reaching it
END IF

The trick is simply not to write any "END" statement that is not the
last one alone on one line, and whatever is on that line must not be
a remark or a string within doublequotes.

2 - All Variables, Arrays, Constants, TYPE Structures, Subprograms names,
Functions names, and Parameters as well as COMMAND LINE Parameters,
if any, must contain at least one lowercase letter.

COMMENTS compares each string in your listing with its uppercase
equivalent. This goes much faster than comparing it against every
QuickBASIC reserved word, but requires the use of lowercase letters.

3 - If you use labels before DATA statements at the beginning of the
module level part of your program, you should write them all in
uppercase. Otherwise, COMMENTS will list them as variables.


Requirements (part 2)


On the other hand, if you use labels after the "END" statement in
error-handling routines, you must slightly modify your listing in
the following way :

DO NOT write an "END" statement before the error-handling
routines, but DO write one after the routines. Then run COMMENTS.
Afterwards, load your program into QuickBASIC, remove the "END"
statement that is after the error-handling routines and add an
"END" statement before the routines.

If you don't modify your program in this way, COMMENTS will either
generate an error message and terminate or it won't copy the
error-handling routines in the new version of your listing.

As for everything else, you may write your program in any way that is
acceptable to QuickBASIC.



How COMMENTS works


COMMENTS opens the file you have selected and then reads each line one by one.
Each time a line is read, it is copied to a backup file. Then remarks and
strings within doublequotes are removed from that line. All characters that
are not numbers or letters are removed and each string left is then analyzed.

Statements such as CONST or DIM tell COMMENTS what the following strings are.
Every important string found is stored in memory and when the whole file as
been read and backed up, your original file is closed and reopened.

The file is then read again, only this time each line is copied to a temporary
file with the same name as your listing but with a .TMP extension. As the file
is read again, each string found that does not match its uppercase equivalent
is compared to the strings in memory and stored according to what it is. This
is why it is important that each variable, SubProgram name, and so forth,
contain at least one lowercase letter. The other way around would have been to
compare each string found with every QuickBASIC reserved word, which would
take much more time.

Once the end of the module level is reached, the .TMP file is closed and a new
file with a .NEW extension is opened. All the module level boxes containing
the appropriate information are written to this file and the .TMP file that
now contains the module level part of your original listing without any
modification is then copied to the .NEW file.


How COMMENTS works (part 2)


The temporary file is then deleted and a new temporary file is opened.
COMMENTS then reads the lines of the original file until the beginning of the
first procedure. Then each new line read is copied to the temporary file while
the listing is again analyzed.

Once the end of the first procedure is reached, the appropriate information
and the temporary file are added to the .NEW file and this process is repeated
until the whole listing has been analyzed.

Note : Anything that you write in your listing after the "END" statement or
above the "SUB" or "FUNCTION" statement in any procedure won't be
copied to the temporary file and therefore will not appear in the final
file.

This allows you to write temporary remarks that you don't want in the
final version of your program. This is also the reason why you should
merge or copy any 'INCLUDE$ file after the "END" statement of the
module level.



About '$INCLUDE files and .MAK files


COMMENTS is intended to be used with programs that use a single module. You
can, however, use it with programs that use an '$INCLUDE file or with programs
that use more than one module.

- If your listing requires an '$INCLUDE file, merge or copy it in your
original listing after the "END" statement of the module level before
saving your listing.

The merged '$INCLUDE file will not appear in the new version of your
listing if you have merged it after the "END" statement. On the other
hand, if you do not merge it, COMMENTS won't be able to identify the
Constants, TYPE structures, and procedures. Therefore, everything will
be listed as variables.

- If you use more than one module, process them one by one. If you use an
'$INCLUDE file, merge it in each module.


How to use COMMENTS


Write your program as you would usually do, but make sure you follow the
requirements stated earlier in this document.

Don't write any remark you want to be in your program after the "END"
statement of the module level or above the "SUB " or "FUNCTION" statement of
any procedure.

Once your program is completed, save it in ASCII format and exit QuickBASIC.

Then call COMMENTS from the directory where your program is. If COMMENTS is in
a subdirectory that appears in the PATH statement of your AUTOEXEC.BAT file,
simply type COMMENTS on the command line and press [ENTER], otherwise, also
type the path to the subdirectory where COMMENTS is.

Select your program from the list of files that appear on screen and answer
each question as you are prompted.


How to use COMMENTS - Answering prompts



COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


ATTRIB .BAS
BIN2HEX .BAS QuickBASIC comments adding utility
BIOSCALL.BAS
BITS .BAS Available to you through the Shareware concept
BOXES .BAS
CALENDAR.BAS Please read the accompanying documentation
DOLLARS .BAS
DOSCALLS.BAS
EDIT .BAS
ERROR .BAS
FILEINFO.BAS Reading directory - Please wait ...
GCURSOR .BAS
HEX2BIN .BAS Please choose the file to add comments to.
KEYS .BAS
MOUSSUBS.BAS [HOME] [END] [PgUp] [PgDn] [Up and Down arrows]
NEWBOXES.BAS
PARSE .BAS [ENTER] to select - [ESC] to quit
STRINGS .BAS


Shown above is what appears on screen when COMMENTS is loaded. Only the
files with a .BAS extension in the current directory will be listed and the
first one will be highlighted.

If there are no .BAS files in the current directory, COMMENTS will display
an error message and exit.

If there are more than 18 files with a .BAS extension in the current
directory, use the cursor keys to highlight the listing you want to process
and press [ENTER].

You may press [ESC] to exit the program.

For example purposes, let's select BOXES.BAS and walk through COMMENTS to
show you how it works. Note that for your convenience, both versions of
BOXES.BAS are included with COMMENTS. This listing is not copyrighted and
you are free to use it in your listings. BOXES.BAS is a toolbox that was
written to draw different kinds of boxes on screen in different listings.
BOXES.BAK is the original listing while BOXES.BAS is the new file written
by COMMENTS. The descriptions that appear in the PARAMETERS and VARIABLES
boxes were added after, not by COMMENTS.

Once you have highlighted BOXES.BAS and pressed [ENTER], the following
screen will appear :


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Making backup copy of Number of declared SubPrograms : 7

BOXES.BAS Number of declared Functions : 0

while reading it. Number of CONST statements : 0

Backup filename is Number of TYPE structures : 0

BOXES.BAK Number of SubPrograms found : 7

Please wait ... Number of Functions found : 0

Command line parameters ? : No

.MAK file required ? : No





At the beginning, all numbers are set to 0 and the "Command line parameters
?" and ".MAK file required ?" lines are not displayed. Each time an
important information is found, the corresponding number is updated and
when the whole file has been analyzed, the "Command line parameters ?" and
".MAK file required ?" lines will be printed with the appropriate "Yes" or
"No".

You will then be prompted to press a key to continue.


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Enter name of program :



















The above screen will then appear, with COMMENTS prompting you to enter the
name of your program.

Type the name of your listing in the highlighted box.

Until you press [ENTER], [Up Arrow], or [Down Arrow], COMMENTS gives you
WordStar-like editing capabilities. That is, you can use [INS] to toggle
overwrite mode on and off, [HOME], [END], [^LEFT], [^RIGHT], [^Q] to erase
the whole line, and [^Q-Y] to erase the end of the line from the cursor
position.


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Enter name of program :

BOXES


Select the Type of the program
Application
[Up and Down arrows] - Move cursor Utility
Toolbox
[ENTER] - Select Demo
Game
Enter type : Other








Once you have pressed [ENTER], [Up Arrow], or [Down Arrow], the screen will
be modified in the way shown above except for the "Enter type :" line and
highlighted box. This appears only if you select "Other".

You can now select the type of your program by highlighting the appropriate
description, using the [Up] or [Down] arrow. If the type of your program
does not appear in the list, select "Other".

If you do select "Other", you again have access to WordStar-like editing
capabilities until you press [ENTER], [Up Arrow], or [Down Arrow].


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Enter name of program :

BOXES


Select the Type of the program
Application
[Up and Down arrows] - Move cursor Utility
Toolbox
[ENTER] - Select Demo
Game
Other


Enter source of program :





The next step is to type in the source of your program. In most cases, it
is your name that you will type there but if the listing comes from a
magazine or a book, or any other source, write the reference here.

Remember the WordStar-like editing capabilities. They apply here as well.


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Enter description of program



















Once you have entered the source of your listing, COMMENTS will prompt you for
its description. The above screen will appear and you will again have access
to editing capabilities.

In this case, though, [ENTER], [Up Arrow], and [Down Arrow] move the cursor
up or down one line. You must press [ESC] to exit from this highlighted
box. Don't worry about exceeding the length of the lines, COMMENTS provides
wrap-around capabilities.

Note, however, that when you exit this box, COMMENTS will concatenate
everything you have written into one line and will then break that line in
as many lines as required to fit the text into the comment box that will be
added to your listing, removing any double spaces in the process.
Therefore, you may not include blank lines within the box while using
COMMENTS, but you may do so when you later load the new version of your
listing in QuickBASIC.

If you want to see what the text will look like in its final version, move
the cursor to the upper left corner of the highlighted box and press the
[BACKSPACE] key.


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Select the Requirements of the program (none)
DOS 2.x
[Up and Down arrows] - Move cursor DOS 3.x
DOS 4.x
[ENTER] - Select/Unselect CGA
EGA
[ESC] - Exit VGA or MCGA
Mouse
Mouse (optional)
Modem
Joystick
Printer
Other
Other
Other
Other
Other
Other


There are still two more things that only you can tell COMMENTS, the
requirements of your program and the language you used to write it. But
both are simple to do.

Shown above is the screen that prompts you for the requirements of your
program. Use the [Up] and [Down] arrows to select each of the requirements
that apply to your program. When all the requirements have been selected,
press [ESC] to exit.

Every time you press [ENTER], the current selection that is highlighted
will be marked. You remove a mark by pressing [ENTER] while highlighting a
selection that is already marked.

When you press [ESC], all requirements marked will be included in the
requirements box added to your listing.

If you need a requirement that is not written as an available selection,
select any of the "Other" lines. COMMENTS will prompt you to type that
requirement. Again, you have access to editing capabilities until you press
[ENTER], [Up], or [Down] arrow. Should you notice too late that you've made
a typing mistake, highlight the requirement line that contains the
misspelled word, unselect it by pressing [ENTER], highlight another "Other"
line, and type a new line.

The "Other" lines are provided so you can add such remarks as '$INCLUDE
files, special libraries, or anything else that is required by your program
to work properly.

Now, the language you used to write your program. Use the [Up] and [Down]
arrows to highlight the version of QuickBASIC that you used or select
"Other" if you used another BASIC language and press [ENTER].


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Select the Requirements of the program (none)
DOS 2.x
[Up and Down arrows] - Move cursor DOS 3.x
DOS 4.x
[ENTER] - Select/Unselect CGA
EGA
[ESC] - Exit VGA or MCGA
Mouse
Mouse (optional)
Modem
Joystick
Select language used in the program Printer
Other
QuickBASIC V. 4.0 Other
QuickBASIC V. 4.5 Other
Other Other
Other
Other


If your program uses Command Line Parameters, another screen will be
displayed and COMMENTS will prompt you to enter the appropriate
information.

To allow you to write each parameter on a different line, the editing
capabilities inside this box are the same as when editing only one line.
Each time you press [ENTER], [Up], or [Down] arrow, the cursor moves to the
next line and you can no longer edit the previous line. To exit from that
box, press [ENTER] on a blank line.


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Now processing : Module level

Variables found : 0 Reading

















Once all the necessary information has been entered, the next screen to appear
will be as shown above. Remember that all these screens were saved while
analyzing BOXES.BAS with COMMENTS.

COMMENTS is now analyzing the module level section of the program. Each
time a new variable (or array) is found, the appropriate number is
displayed. When the "END" statement is reached, "Reading" is replaced by
"Writing". COMMENTS then writes the appropriate boxes to the .NEW file and
copies the temporary file after the boxes.


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Now processing : SUBPROGRAM DoubleBorderBox

Variables found : 1 Procedure # 1 of 7 Reading

















COMMENTS then resumes reading the file and when it finds the first
procedure, it will replace "Module level" by either "SUBPROGRAM" or
"FUNCTION" and will display the name of the procedure it is reading. Again
the number of variables found is shown. COMMENTS also tells how many
procedures it will have to process and which is the one that is currently
being read.

When COMMENTS finds an "END SUB" or "END FUNCTION" statement, actually the
end of the procedure it was reading, a message and a highlighted box will
appear on screen and COMMENTS will prompt you for the description of that
procedure. Once you've typed it, COMMENTS will resume its reading.


COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software


Now processing : SUBPROGRAM DoubleBorderBox

Variables found : 1 Procedure # 1 of 7 Writing


Enter description of procedure














When prompted to type the description of a procedure, the editing
capabilities are the same as when entering the description of the program
itself. Exit by pressing [ESC].

When the last procedure has been processed, the original .BAS file will be
deleted (Remember that a copy with a .BAK extension was made when the file was
read the first time) and the .NEW file is renamed with a .BAS extension.

COMMENTS will then display a message telling that it is writting the structure
file and when this is completed, it will display another message telling you
that the processing of your listing is completed and prompting you to press a
key to exit the program.

When your computer is back to the command line, you should load QuickBASIC,
call your program and then add remarks in the overstrike mode for each of
the variables and parameters that COMMENTS has identified in your program.

If you wish, you may merge the structure file to the main module of your
program since each line begins with an apostrophe and the whole file is
written in the same format as the other information that was added to your
listing.

Note that you can use COMMENTS before the final version of your program is
completed. This might prove useful to find where there is a misspelled
variable since both versions of that variable will be added to your listing
in the variables list. Remember though that COMMENTS will write new boxes
when you run it again on the new listing with a .BAS extension. If you use
COMMENTS on a version of your program that is not the final one, delete the
.BAS file after you've looked at it and rename the .BAK file with a .BAS
extension so you use again your original listing.


COMMENTS Limitations


COMMENTS will display an error message and terminate if your listing
exceeds these limits :

100 files with a .BAS extension in the current directory
25 files in a .MAK file

60 Constants
25 TYPE structures
40 variables in any TYPE structure

100 Subprograms
60 Functions

100 different arrays in the whole listing
100 variables and arrays used within any procedure

COMMENTS will also terminate if there is no "END" statement at the end of
the module level section of your listing.

Note : When COMMENTS terminates because of a problem, it doesn't erase any
file. Therefore you may find a ".BAK", ".TMP", or ".NEW" file in
your directory. These files need not be deleted since COMMENTS will
overwrite them the next time you use it for the same listing.

Also note that the original file is renamed only when the whole process is
completed. So should COMMENTS stop because of any problem, DO NOT erase the
".BAS" file and rename the ".BAK" file. The ".BAS" file is your original
listing. The ".BAK" file is a copy of it, but if COMMENTS stopped before it
had time to copy all the lines of your original listing, the ".BAK" file is
not complete.

If a problem occurs, note the error message and look at the ".BAK", ".TMP",
and ".NEW" files. You will then easily find out why COMMENTS stopped.


About Shareware


COMMENTS is distributed through the Shareware concept. You are therefore
encouraged to make copies and give them to anyone who might use it. We
would also greatly appreciate it if you help us make it available to more
users by uploading it to any BBS you have access to.

The registration fee for COMMENTS is $ 20.00. Anyone who sends $ 30.00 or
more will receive Version 2 as soon as it is available.

Please support the Shareware concept. If you use COMMENTS, send your
registration fee to the following address:

LAMCO Software
P.O. Box 46
Postal Station P.A.T.
Montreal, Quebec, Canada
H1B 5K1

Please state the program name and the version number.

Help us make a better product available to you. Send us your suggestions
and please report any problem.

COMMENTS was written with QuickBASIC version 4.5 and is intended to be used
with either version 4.0 or 4.5 of QuickBASIC, but you may use it with other
versions of QuickBASIC or other BASIC languages, as long as your listing
was saved in ASCII format. If you use COMMENTS with another BASIC language
and you find that COMMENTS doesn't work properly, please write to us,
describing what happened. Maybe we can modify COMMENTS so Version 2 will
accept the other BASIC languages as well or at least tell you how you could
write your program so COMMENTS will work.



What's coming up in version 2.0


When a .MAK file is used, Version 2 will be able to process all the modules
and read the '$INCLUDE files. The Structure file will also indicate in which
module is each procedure called.

Comments added to your listing will be updated rather than overwritten, so
you won't have to type in the same information twice or more if you run
COMMENTS more than once for the same listing.

Version 2 will also include configuration possibilities, so you can set the
colors and type in only once options that you use often in your listings,
such as Requirements, Source, or Language.

We will also, of course, consider any suggestion we will receive from you,
the user.