Delete
(int,int, Event, bdeGraph)
(path:[an error occurred while processing this directive] file:javadocDev.shtml)
The main objective of this project (96f523/bde2java) was to generate documentation in javadoc style using the javadoc facility supplied by the java development kit (from javajdk ver 1.0). This document is meant to serve as a quick reference to the following issues:
The process of understanding the code has took a lot of time due to this lack of documentation. Some of the original comments did not match the real funtionality of the code. There is also a lot of unused code in the program. At least 20 out of the 200 methods are empty or are not being called. Some methods are so similar to other methods that we do not understand the reason the programmer needed to implement two seperate ones. Some of the code we are not able to understand completely. The difficulty of understanding the code is reflected in the given log files as we spent a lot of time on decoding the code itself.
We had experienced some difficulty in compiling and ruuning bde2java, again due to lack of instructions from previous project. We finally were able to compile bde2java on both PC and workstation. Though we were able to run bde2java on a PC, we still have difficulty in running bde2java from a workstation apparently due to the problems inside the interptreter of javajdk used in our CS system. For the purpose of letting other students easier in compiling and running bde2java, we have written some brief instrustions and steps that they can follow in this report (see sections 3-5)
We had found out some of the special properties of javadoc that we need to pay attention to. As a result we need to put down our code documentation in a special way.
The following is an example of the a piece of code showing the difference in javadoc before and after modification.
.
.
/*************************************************************
* Method: public void Delete()
*
* Description:
*
* Class: bdeNode
*
*
*************************************************************/
.
.
.
public static void Delete(int x,
int y,
Event evt,
bdeGraph parent)
.
.
.
/* ******************************************************************/
/**
* <pre>
* Method : Delete()
* Description : Delete a node, depending on mouse event,
* if it has not a link
* State : evt.modifiers = Event.META_MASK
* --> print a message
* evt.id = MOUSE_DOWN
* --> select node for given (x,y)
* set FirstSelectedNode.selected = true
* evt.id = MOUSE_UP
* --> check if current node is the same
* node as FirstSelectedNode
* if yes --> delect the node,
* update links
* if no --> set
* FirstSelectedNode.selected = false,
* return
* Class : bdeNode
* </pre>
* @param
* <pre>
* (x,y) node point
* </pre>
* @param
* <pre>
* evt event in case of,
* MOUSE_DOWN, get selected node or NOT_FOUND
* MOUSE_UP, if not NOT_FOUND, get number of links
* of the selected node, delete it, update
* parent list, and repaint it
* </pre>
* @return None
* @exeception None
*/
/* ******************************************************************/
.
.
.
Delete(int,
int, Event, bdeGraph)
Method : Delete()
Description : Delete a node, depending on mouse event,
if it has not a link
State : evt.modifiers = Event.META_MASK
--> print a message
evt.id = MOUSE_DOWN
--> select node for given (x,y)
set FirstSelectedNode.selected = true
evt.id = MOUSE_UP
--> check if current node is the same
node as FirstSelectedNode
if yes --> delect the node,
update links
if no --> set
FirstSelectedNode.selected = false,
return
Class : bdeNode
public static void Delete(int x,
int y,
Event evt,
bdeGraph parent)
Method : Delete()
Description : Delete a node, depending on mouse event,
if it has not a link
State : evt.modifiers = Event.META_MASK
--> print a message
evt.id = MOUSE_DOWN
--> select node for given (x,y)
set FirstSelectedNode.selected = true
evt.id = MOUSE_UP
--> check if current node is the same
node as FirstSelectedNode
if yes --> delect the node,
update links
if no --> set
FirstSelectedNode.selected = false,
return
Class : bdeNode
(x,y) - node point
evt - event in case of,
MOUSE_DOWN, get selected node or NOT_FOUND
MOUSE_UP, if not NOT_FOUND, get number of links
of the selected node, delete it, update
parent list, and repaint it
/* ***...*/ : tell javadoc do not pick up this line
(not for javadoc). For use with code delimeters.
/** : start to convert (generate) the following
documentation into .html file (source_filename.html)
*/ : end of javadoc segment
<pre>...</pre>: shows everything between the tags
literally [preformat]
Note: Usage of "." inside the tags can
generate formatting errors - AVOID
@param single-string : define input paramenter
if you have more than one string in the documentation,
you have to use:
@param
<pre>
paramenter_name_1 description
</pre>
@param
<pre>
paramenter_name_2 descrption
</pre>
Note: javadoc only considers the first word as the input
paramnter. In case of two input paramenters, two
@param required.
@return single-string : define return result
in case of multiple returned paramenters:
@return
<pre>
return_name_1 return_name_2 ... (or descption)
</pre>
@exception single-string : define side-effect
also,
@exception
<pre>
....
</pre>
PS: @param, @return and @exception will show up in method
description of On a PC:
1) ftp all the .java files to the PC
2) compile the .java files by
/java/bin/javac bdeJava java
it will then generate a number of .class files.
3) run bde2java by
/java/bin/java bdeJava
the program will then come up.
On a workstation:
1) set the system variable by
setenv SYSNAME alpha_osf32c
2) compile the .java files by
/usr/proj3/case/javajdk/bin/javac bdeJava java
it will then generate a number of .class files.
3) run bde2java by
/usr/proj3/case/javajdk/bin/javac bdeJava
Unfortunately, due to some problems existing in the interpreter of the jdk, bdeJava probably will not run. A window for bdeJava will come up for a tenth of a second and then crash. It is possible that updates to jdk may remedy the problem.
On a PC:
1) ftp the .java to the PC. example: bdeCaptionText.java
2) run javadoc by
/java/bin/javadoc bdeCaptionText.java
it will then generate the bdeCaptionText.html file
On a workstation:
1) set the system vairable by
setenv SYSNAME alpha_osf32c
2) run javadoc by
/usr/proj3/case/javajdk/bin/javadoc bdeCaptionText.java
it will then genereate the bdeCpationText.html
COMPILED LOGS:
Wing-kin (Steve) AU's log:
learning Java : 45 hrs
trying jdk compiler and javadoc on both platforms : 25 hrs
Understanding the code : 60 hrs
Adding comment : 30 hrs
Li Fu Wang's log:
Learning_java : 55 hrs
Understanding the code : 50 hrs
Addng comment : 50 hrs
Zhigang Wang's log:
Learning Java : 55 hrs
Understanding the code : 50 hrs
Adding comment : 55 hrs
DOCUMENTATION SUBGROUP TOTAL HRS: 480 man hrs.
This reflects time spent over the semester development period.
[an error occurred while processing this directive]/javadocDev.shtml
Last updated: Friday, 20-Dec-1996 21:30:43 EST