Difference between revisions of "ESAPI Javadocs"

From OWASP
Jump to: navigation, search
(To Generate Javadocs)
(To Generate Javadocs)
Line 5: Line 5:
 
# ''Be sure you are in the Java EE perspective.''  To change your perspective, click the ''Window'' button on the main toolbar.  Then click ''Open Perspective'' and choose ''Java EE''.  If Java EE is not in the list, select ''Other..'' and find ''Java EE''.  If Java EE is not in the list under Other, you may need to download Eclipse Ganymede (v3.4) for Java EE developers.  Javadoc creation functionality may be built into your version of Eclipse, but that has not been tested.
 
# ''Be sure you are in the Java EE perspective.''  To change your perspective, click the ''Window'' button on the main toolbar.  Then click ''Open Perspective'' and choose ''Java EE''.  If Java EE is not in the list, select ''Other..'' and find ''Java EE''.  If Java EE is not in the list under Other, you may need to download Eclipse Ganymede (v3.4) for Java EE developers.  Javadoc creation functionality may be built into your version of Eclipse, but that has not been tested.
 
# Then, click the ''Project'' button on the main toolbar.  Select ''Generate Javadoc...''
 
# Then, click the ''Project'' button on the main toolbar.  Select ''Generate Javadoc...''
# Choose the Javadoc command to use.  This should point to javadoc.exe within your j2sdk bin directory, as shown in figure 1.
+
# Find the Javadoc executable to use.  This is usually javadoc.exe within your java bin directory, as shown in figure 1.
 
# Select the ESAPI source, but not the test files within your ESAPI project, as shown in figure 1.
 
# Select the ESAPI source, but not the test files within your ESAPI project, as shown in figure 1.
# You should create Javadoc for members with visibility: Public, as shown in figure 1.
+
# You should create Javadoc for members with visibility: Package, as shown in figure 1.
 
# Select the Javadoc output directory.  This will likely be /doc under your ESAPI project folder.
 
# Select the Javadoc output directory.  This will likely be /doc under your ESAPI project folder.
 +
# Click ''Next''.
 +
 
Figure 1:
 
Figure 1:
  
 
http://owasp-esapi-java.googlecode.com/svn/trunk/javadoc/org/owasp/esapi/doc-files/wiki/Generate%20Javadoc1.jpg
 
http://owasp-esapi-java.googlecode.com/svn/trunk/javadoc/org/owasp/esapi/doc-files/wiki/Generate%20Javadoc1.jpg
  
# Click ''Next''.
 
 
# Designate a title for this Javadoc.  Generally, this should be "OWASP Enterprise Security API (ESAPI)".
 
# Designate a title for this Javadoc.  Generally, this should be "OWASP Enterprise Security API (ESAPI)".
# Under Basic Options, all checkboxes should be selected, as shown in Figure 2.
+
# Use Default: Under Basic Options, make sure all checkboxes are selected, as shown in Figure 2.
# Javadocs for referenced archives should not be generated, as shown in Figure 2.
+
# Use Default: Make sure Javadocs for referenced archives are not generated, as shown in Figure 2.
# Generally, no style sheet should be used, as shown in Figure 2.
+
# Use Default: No custom style sheet should be specified, as shown in Figure 2.
 +
# Click ''Next''.
 +
 
 
Figure 2:
 
Figure 2:
  
 
http://owasp-esapi-java.googlecode.com/svn-history/r262/trunk/javadoc/org/owasp/esapi/doc-files/wiki/Generate%20Javadoc2.jpg
 
http://owasp-esapi-java.googlecode.com/svn-history/r262/trunk/javadoc/org/owasp/esapi/doc-files/wiki/Generate%20Javadoc2.jpg
  
# Click ''Next''.
 
 
# ''The Overview page must be selected, as shown in Figure 3''.  ''It should point to overview-summary.html in the javadoc resources folder''.
 
# ''The Overview page must be selected, as shown in Figure 3''.  ''It should point to overview-summary.html in the javadoc resources folder''.
# The JRE source compatibility should be selected as 1.4, as shown in Figure 3.
+
# Use Default: The JRE source compatibility should be selected as 1.4, as shown in Figure 3.
 +
# Click ''Finish''.
 +
 
 
Figure 3:  
 
Figure 3:  
  
 
http://owasp-esapi-java.googlecode.com/svn-history/r262/trunk/javadoc/org/owasp/esapi/doc-files/wiki/Generate%20Javadoc3.jpg
 
http://owasp-esapi-java.googlecode.com/svn-history/r262/trunk/javadoc/org/owasp/esapi/doc-files/wiki/Generate%20Javadoc3.jpg
  
# Lastly, if it isn't already there, copy the folder "doc-files" from "javadoc resources" to org/owasp/esapi within your new javadoc directory. If you receive errors regarding version control, follow the steps below.
+
# If it isn't already there, copy the folder "doc-files" from "javadoc resources" to org/owasp/esapi within your new javadoc directory.
 +
# To view these new javadocs, double click on: <yourdocsfolder>/index.html
 +
 
 +
=== Submitting these new javadocs to SVN ===
 +
# To submit these newly generated javadocs, simply use Team --> Commit in Eclipse. Note: Please check in updates into the existing /doc directory, rather than creating a new directory.
 +
# If you receive version control errors during the submit, follow the following steps:
 
* Navigate to your ESAPI Project/javadoc/org/owasp/esapi/doc-files directory.
 
* Navigate to your ESAPI Project/javadoc/org/owasp/esapi/doc-files directory.
 
* Delete the folder called .svn from this folder and all subdirectories (wiki).
 
* Delete the folder called .svn from this folder and all subdirectories (wiki).

Revision as of 13:31, 21 October 2008

Contents

How to create Javadocs for ESAPI using Eclipse v3.4

First off, notice a folder called "javadoc resources" in the root directory of your ESAPI project. This folder contains images referenced from the Javadoc as well as overview-summary.html, which is the title page for the ESAPI Javadoc. The instructions below make reference to these files.

To Generate Javadocs

  1. Be sure you are in the Java EE perspective. To change your perspective, click the Window button on the main toolbar. Then click Open Perspective and choose Java EE. If Java EE is not in the list, select Other.. and find Java EE. If Java EE is not in the list under Other, you may need to download Eclipse Ganymede (v3.4) for Java EE developers. Javadoc creation functionality may be built into your version of Eclipse, but that has not been tested.
  2. Then, click the Project button on the main toolbar. Select Generate Javadoc...
  3. Find the Javadoc executable to use. This is usually javadoc.exe within your java bin directory, as shown in figure 1.
  4. Select the ESAPI source, but not the test files within your ESAPI project, as shown in figure 1.
  5. You should create Javadoc for members with visibility: Package, as shown in figure 1.
  6. Select the Javadoc output directory. This will likely be /doc under your ESAPI project folder.
  7. Click Next.

Figure 1:

Generate%20Javadoc1.jpg

  1. Designate a title for this Javadoc. Generally, this should be "OWASP Enterprise Security API (ESAPI)".
  2. Use Default: Under Basic Options, make sure all checkboxes are selected, as shown in Figure 2.
  3. Use Default: Make sure Javadocs for referenced archives are not generated, as shown in Figure 2.
  4. Use Default: No custom style sheet should be specified, as shown in Figure 2.
  5. Click Next.

Figure 2:

Generate%20Javadoc2.jpg

  1. The Overview page must be selected, as shown in Figure 3. It should point to overview-summary.html in the javadoc resources folder.
  2. Use Default: The JRE source compatibility should be selected as 1.4, as shown in Figure 3.
  3. Click Finish.

Figure 3:

Generate%20Javadoc3.jpg

  1. If it isn't already there, copy the folder "doc-files" from "javadoc resources" to org/owasp/esapi within your new javadoc directory.
  2. To view these new javadocs, double click on: <yourdocsfolder>/index.html

Submitting these new javadocs to SVN

  1. To submit these newly generated javadocs, simply use Team --> Commit in Eclipse. Note: Please check in updates into the existing /doc directory, rather than creating a new directory.
  2. If you receive version control errors during the submit, follow the following steps:
  • Navigate to your ESAPI Project/javadoc/org/owasp/esapi/doc-files directory.
  • Delete the folder called .svn from this folder and all subdirectories (wiki).
  • In the Navigator view in Eclipse, Right-click the doc-files folder and select "Team" -> "Add to svn:ignore...".
  • In the Navigator view in Eclipse, Right-click the doc-files folder again and select "Team" -> "Add to Version Control". You should receive a message saying that you previously asked to ignore this file. Click yes.

Why do my newly generated Javadocs render as plain text in my browser?

Unfortunately, using this method of Javadoc generation does not set MIME types for the HTML files generated. This means that to the browser, your HTML files are just text files, and will display as such. Luckily Subclipse has a function to fix this.

  1. Right-click on any Javadoc folder that contains ONLY HTML files (If the folder contains other file types, like images, this will change their MIME type, making them render improperly in the browser). Most of the Javadoc folders will contain only HTML files, but because some images exists, you cannot perform this action for the root Javadoc directory.
  2. Select "Team" -> "Set Property..."
  3. In the Property name box, type "svn:mime-type" with no surrounding quotes.
  4. In the text property box, type "text/html" with no surrounding quotes.
  5. Select "Set property recursively" to set this property for all files within that directory, and all subdirectories.
  • See Figure 4 below for an example.

Figure 4:

set_mime-type.jpg

MIME types should not need to be set for any image files. Your Javadoc should be ready to view!