Slides Only

idiotdiscΛογισμικό & κατασκευή λογ/κού

15 Αυγ 2012 (πριν από 5 χρόνια και 3 μήνες)

194 εμφανίσεις

1


JAVA DOC

Java Doc is a documentation tool that allows you to create an html page of all your methods like those

that see when you look up a java class in the Java API. Because NetBeans and Eclipse will generate the
html page for you (and those instructio
ns are here for NetBeans), I have not required it in 1052 .
However, I want you to know how to do it yourselves so you must do it in at least one class in your GUI
competition project. You will hand in the html page in your project folder. You must also

fully
document all your other methods and classes and there will be points deducted if the documentation
is not complete.


In NetBeans:

Set up a project( or import one in if you are working in another editor).

For java doc , under run, choose


“generate

javadoc”


NetBeans creates the javadoc html file which it will load in a
browser
window. In the
browse
window
to the left
,

the
html
file is displayed and you can then save that html file to your folder with the other
files

Below are the steps you need t
o take to cre
ate that documentation yourself from the command
prompt. It would be easier to just create the html directory in windows first.






2


You will do the above steps from the command prompt in the directory where your project is.

You should have c
reated the doc directory and use its full path name, e.g. c:
\
EddieFiles
\
doc

if it is not in the same folder as your project

To reiterate:

There are three easy steps to having the HTML documentation for a class generated by
javadoc
.
These steps are describe
d above.

Step 1. Make

a

directory for HTML documentation
.

You may want to make a directory within the directory in which the
.java

or
.class

class
definition is stored. You need the
.java

file to produce the
javdoc

documentation.

Y
ou can store it in a d
irectory on your local machine and view the local

files using a browser


Step
2.
Execute
javadoc
.


Execute the
javadoc

program.
(
FIRST YOU MUST HAVE THE FILE COMPILED)
. It

is
included with the Java Development Kit and so it should be available in the same

way you run
javac

and
java

from the
command prompt
. When you compile class definitions with
javac
, you
execute the command
javac

followed by the name of the class definition. For example,
javac
Reverse3.java
.

Similarly, when you generate
javadoc

for a cl
ass definition, you execute the command
javadoc

followed by the name of the class definition and then followed by
-
d

and then the relative
directory path to the directory in which you want the resulting HTML file(s) stored.
For
example
: javadoc

Reverse3.j
ava


d html ( where html is name of the directory where you will
store you javadoc classes.)

Step 3. View
javadoc

results.

Use your browser on the javadoc html page in your html directory

Over the next few slides, we will walk through these three steps usi
ng the
Reverse3

program.

Example

JavaDoc documentation


/**


* Returns an Image object that can then be painted on the screen.


* The url argument must specify an absolute
{@link URL}
. The name


* argument is a specifier that is relative to the url argument.


* <p>


* This method always returns immediately, whether or not the


* image exists. When this applet attempts to draw the image on


* the screen, the data will b
e loaded. The graphics primitives


* that draw the image will incrementally paint on the screen.


*


*
@param

url

an absolute URL giving the base location of the image


*
@param

name

the location

of the image, relative to the url argument


*
@return

the imag
e at the specified URL


*
@see

Image

3


public Image getImage(URL url String name)

{


try {



return getImage(getURL(name));


} catch (Exception e) {



return null;


}


}



protected URL getURL(String filename) {


URL codeBase = this.getCodeBase();


URL url = null;



try {


url = new URL(codeBase, filename);


} catch (java.net.MalformedURLException e) {


System.out.println("
Couldn't create image: badly specified URL");


return null;


}



return url;


}


}





Notes:




The
resulting HTML

from running Javadoc is s
hown below



Each line above is indented to align with the code below the comment.



The first line contains the begin
-
comment delimiter
(
/**
).



Starting with Javadoc 1.4, the
leading asterisks are optional
.



Write the first sentence as a short summary of the method, as
Javadoc automatically
places it in the method summary table (and index).



Notice the inline tag
{@link URL}
, which converts to an HTML hype
rlink pointing to the
documentation for the URL class.



If you have more than one paragraph in the doc comment, separate the paragraphs with a
<p>

paragraph tag, as shown.



Insert a
blank comment line

between the description and the list of tags, as shown.




The first line that begins with an "@" character ends the description. There is only one
description block per doc comment;



The last line contains the end
-
comment delimiter (
*/
) Note that unlike the begin
-
comment delimiter, the end
-
comment contains only

a single asterisk.

For more examples, see
Simple Examples
.

4


So lines won't wrap, limit any doc
-
comment lines to 80 characters.

Here is what the

html page

would look like

after running the Javadoc tool:

Reverse3

public
Reverse3
()

Method Detail

getImage

public java.awt.Image
getImage
(java.net.URL

url,


java.lang.String

name)

Returns an Image object that can then be painted on the screen. The
url argument must
specify an absolute
URL
. The name argument is a specifier that is relative to the url
argument.

This method always returns immediately, whether or not the image exists. When this
applet attempts to draw the image on the screen, the data
will be loaded. The graphics
primitives that draw the image will incrementally paint on the screen.

Overrides:

getImage

in class
java.applet.Applet

Parameters:

url

-

an absolute URL giving the base location of the image

name

-

the location of the image, r
elative to the url argument

Returns:

the image at the specified URL

See Also:

Image


getURL

protected java.net.URL
getURL
(java.lang.String

filename)