[icedtea-web 1.0] RFC: Documentation fixes
Dr Andrew John Hughes
ahughes at redhat.com
Tue Dec 7 15:19:16 PST 2010
The attached patch fixes a number of warnings arising from the documentation
generation process (broken @param & @return usage mainly).
Ok for HEAD and 1.0 branch?
2010-12-07 Andrew John Hughes <ahughes at redhat.com>
* netx/net/sourceforge/jnlp/InformationDesc.java,
(InformationDesc(JNLPFile,Locale)): Correct @param tag.
* netx/net/sourceforge/jnlp/JARDesc.java:
(JARDesc(URL,Version,String,boolean,boolean,boolean,boolean)):
Correct typo and add missing @param tag for cacheable.
* netx/net/sourceforge/jnlp/JREDesc.java:
(JREDesc(Version,URL,String,String,String,List)): Correct typo
in @param tag.
* netx/net/sourceforge/jnlp/Launcher.java:
(Launcher(boolean)): Correct broken @param tag.
* netx/net/sourceforge/jnlp/cache/ResourceTracker.java:
(addDownloadListener(DownloadListener)): Remove broken @param tags.
Add correct one.
(removeDownloadListener(DownloadListener)): Add missing @param tag.
* netx/net/sourceforge/jnlp/security/KeyStores.java:
(getKeyStoreLocation(Level,Type)): Add content to @param and @return tags.
(toTranslatableString(Level,Type)): Likewise.
* netx/net/sourceforge/jnlp/security/PasswordAuthenticationDialog.java:
(askUser(String,int,String,String)): Correct typo in @param tag.
* netx/net/sourceforge/jnlp/security/SecurityDialogPanel.java:
(createSetValueListener(SecurityWarningDialog,int)): Add content to @return tag.
* netx/net/sourceforge/jnlp/security/SecurityWarningDialog.java:
(showCertInfoDialog(CertVerifier,SecurityWarningDialog)): Remove broken
@param tag and add correct ones.
(showSingleCertInfoDialog(X509Certificate,JDialog)): Add content to @param tags.
* netx/net/sourceforge/jnlp/tools/CharacterEncoder.java:
Remove broken @see tags from import from OpenJDK.
* netx/net/sourceforge/jnlp/tools/KeyTool.java:
(checkCacertsForCertificate(Certificate)): Correct typo in @returns tag.
* netx/net/sourceforge/jnlp/util/FileUtils.java:
Fix bad whitespace.
(sanitizeFileName(String)): Fix @param tag.
* netx/net/sourceforge/nanoxml/XMLElement.java:
Fix example in class documentation.
* plugin/icedteanp/java/sun/applet/PluginAppletViewer.java,
(waitForAppletInit(NetxPanel)): Fix @param tag.
--
Andrew :)
Free Java Software Engineer
Red Hat, Inc. (http://www.redhat.com)
Support Free Java!
Contribute to GNU Classpath and IcedTea
http://www.gnu.org/software/classpath
http://icedtea.classpath.org
PGP Key: 94EFD9D8 (http://subkeys.pgp.net)
Fingerprint = F8EF F1EA 401E 2E60 15FA 7927 142C 2591 94EF D9D8
-------------- next part --------------
diff -r 72471ae86379 netx/net/sourceforge/jnlp/InformationDesc.java
--- a/netx/net/sourceforge/jnlp/InformationDesc.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/InformationDesc.java Tue Dec 07 23:10:34 2010 +0000
@@ -60,7 +60,7 @@
* Create an information element object.
*
* @param jnlpFile file that the information is for
- * @param locale the the information is for
+ * @param locales the locales the information is for
*/
public InformationDesc(JNLPFile jnlpFile, Locale locales[]) {
this.jnlpFile = jnlpFile;
diff -r 72471ae86379 netx/net/sourceforge/jnlp/JARDesc.java
--- a/netx/net/sourceforge/jnlp/JARDesc.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/JARDesc.java Tue Dec 07 23:10:34 2010 +0000
@@ -57,7 +57,8 @@
* @param part the part name, or null
* @param lazy whether to load the JAR on demand
* @param main whether the JAR contains the main class
- * @param nativeJam whether the JAR contains native libraries
+ * @param nativeJar whether the JAR contains native libraries
+ * @param cacheable whether the JAR can be cached or not
*/
public JARDesc(URL location, Version version, String part, boolean lazy, boolean main, boolean nativeJar, boolean cacheable) {
this.location = location;
diff -r 72471ae86379 netx/net/sourceforge/jnlp/JREDesc.java
--- a/netx/net/sourceforge/jnlp/JREDesc.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/JREDesc.java Tue Dec 07 23:10:34 2010 +0000
@@ -55,7 +55,7 @@
* if location is not null
* @param location the location of a JRE product or null
* @param initialHeapSize inital heap size
- * @param maximumHeadSize maximum head size
+ * @param maximumHeapSize maximum head size
* @param resources list of ResourceDesc objects
*/
public JREDesc(Version version, URL location,
diff -r 72471ae86379 netx/net/sourceforge/jnlp/Launcher.java
--- a/netx/net/sourceforge/jnlp/Launcher.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/Launcher.java Tue Dec 07 23:10:34 2010 +0000
@@ -104,7 +104,7 @@
* Create a launcher with the runtime's default update policy
* and launch handler.
*
- * @param exitOnError Exit if there is an error (usually default, but false when being used from the plugin)
+ * @param exitOnFailure Exit if there is an error (usually default, but false when being used from the plugin)
*/
public Launcher(boolean exitOnFailure) {
this(null, null);
diff -r 72471ae86379 netx/net/sourceforge/jnlp/cache/ResourceTracker.java
--- a/netx/net/sourceforge/jnlp/cache/ResourceTracker.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/cache/ResourceTracker.java Tue Dec 07 23:10:34 2010 +0000
@@ -263,8 +263,7 @@
* Adds the listener to the list of objects interested in
* receivind DownloadEvents.<p>
*
- * @param location the resource to add a callback for
- * @param runnable the runnable to call when resource is completed
+ * @param listener the listener to add.
*/
public void addDownloadListener(DownloadListener listener) {
synchronized (listeners) {
@@ -275,6 +274,8 @@
/**
* Removes a download listener.
+ *
+ * @param listener the listener to remove.
*/
public void removeDownloadListener(DownloadListener listener) {
synchronized (listeners) {
diff -r 72471ae86379 netx/net/sourceforge/jnlp/security/KeyStores.java
--- a/netx/net/sourceforge/jnlp/security/KeyStores.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/security/KeyStores.java Tue Dec 07 23:10:34 2010 +0000
@@ -220,9 +220,10 @@
/**
* Returns the location of a KeyStore corresponding to the given level and type.
- * @param level
- * @param type
- * @return
+ *
+ * @param level the specified level of the key store to be returned.
+ * @param type the specified type of the key store to be returned.
+ * @return the location of the key store.
*/
public static final String getKeyStoreLocation(Level level, Type type) {
String configKey = null;
@@ -280,9 +281,9 @@
* concatenating a level and type, converting everything to Title Case and
* removing the _'s. (USER,CA_CERTS) becomes UserCaCerts.
*
- * @param level
- * @param type
- * @return
+ * @param level the level of the key store.
+ * @param type the type of the key store.
+ * @return the translation key.
*/
public static final String toTranslatableString(Level level, Type type) {
StringBuilder response = new StringBuilder();
diff -r 72471ae86379 netx/net/sourceforge/jnlp/security/PasswordAuthenticationDialog.java
--- a/netx/net/sourceforge/jnlp/security/PasswordAuthenticationDialog.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/security/PasswordAuthenticationDialog.java Tue Dec 07 23:10:34 2010 +0000
@@ -184,7 +184,7 @@
/**
* Present a dialog to the user asking them for authentication information
*
- * @param hostThe host for with authentication is needed
+ * @param host The host for with authentication is needed
* @param port The port being accessed
* @param prompt The prompt (realm) as presented by the server
* @param type The type of server (proxy/web)
diff -r 72471ae86379 netx/net/sourceforge/jnlp/security/SecurityDialogPanel.java
--- a/netx/net/sourceforge/jnlp/security/SecurityDialogPanel.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/security/SecurityDialogPanel.java Tue Dec 07 23:10:34 2010 +0000
@@ -78,7 +78,7 @@
* is invoked, it will set the value of the {@link SecurityWarningDialog} and then dispossed.
*
* @param buttonIndex the index of the button. By convention 0 = Yes. 1 = No, 2 = Cancel
- * @return
+ * @return the ActionListener instance.
*/
protected ActionListener createSetValueListener(SecurityWarningDialog dialog, int buttonIndex) {
return new SetValueHandler(dialog, buttonIndex);
diff -r 72471ae86379 netx/net/sourceforge/jnlp/security/SecurityWarningDialog.java
--- a/netx/net/sourceforge/jnlp/security/SecurityWarningDialog.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/security/SecurityWarningDialog.java Tue Dec 07 23:10:34 2010 +0000
@@ -175,7 +175,8 @@
/**
* Displays CertPath information in a readable table format.
*
- * @param certs the certificates used in signing.
+ * @param jarSigner the JarSigner used to verify this application
+ * @param parent the parent option pane
*/
public static void showCertInfoDialog(CertVerifier jarSigner,
SecurityWarningDialog parent) {
@@ -190,8 +191,8 @@
/**
* Displays a single certificate's information.
*
- * @param c
- * @param optionPane
+ * @param c the X509 certificate.
+ * @param parent the parent pane.
*/
public static void showSingleCertInfoDialog(X509Certificate c,
JDialog parent) {
diff -r 72471ae86379 netx/net/sourceforge/jnlp/tools/CharacterEncoder.java
--- a/netx/net/sourceforge/jnlp/tools/CharacterEncoder.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/tools/CharacterEncoder.java Tue Dec 07 23:10:34 2010 +0000
@@ -67,10 +67,7 @@
* referenced in the See Also list below.
*
* @author Chuck McManis
- * @see CharacterDecoder;
- * @see UCEncoder
- * @see UUEncoder
- * @see BASE64Encoder
+ * @see HexDumpEncoder
*/
public abstract class CharacterEncoder {
diff -r 72471ae86379 netx/net/sourceforge/jnlp/tools/KeyTool.java
--- a/netx/net/sourceforge/jnlp/tools/KeyTool.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/tools/KeyTool.java Tue Dec 07 23:10:34 2010 +0000
@@ -259,7 +259,7 @@
* Checks if a given certificate is part of the user's cacerts
* keystore.
* @param c the certificate to check
- * @returns true if the certificate is in the user's cacerts and
+ * @return true if the certificate is in the user's cacerts and
* false otherwise
*/
public boolean checkCacertsForCertificate(Certificate c) throws Exception {
diff -r 72471ae86379 netx/net/sourceforge/jnlp/util/FileUtils.java
--- a/netx/net/sourceforge/jnlp/util/FileUtils.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/jnlp/util/FileUtils.java Tue Dec 07 23:10:34 2010 +0000
@@ -61,7 +61,7 @@
* Given an input, return a sanitized form of the input suitable for use as
* a file/directory name
*
- * @param input
+ * @param filename the filename to sanitize.
* @return a sanitized version of the input
*/
public static String sanitizeFileName(String filename) {
@@ -172,7 +172,7 @@
/*
* use a very simple method: prefix + "..." + suffix
*
- * where prefix is the beginning part of path (as much as we can squeeze in)
+ * where prefix is the beginning part of path (as much as we can squeeze in)
* and suffix is the end path of path
*/
diff -r 72471ae86379 netx/net/sourceforge/nanoxml/XMLElement.java
--- a/netx/net/sourceforge/nanoxml/XMLElement.java Tue Dec 07 15:50:16 2010 -0500
+++ b/netx/net/sourceforge/nanoxml/XMLElement.java Tue Dec 07 23:10:34 2010 +0000
@@ -52,14 +52,14 @@
* You can enumerate the attributes of an element using the method
* {@link #enumerateAttributeNames() enumerateAttributeNames}.
* The attribute values can be retrieved using the method
- * {@link #getStringAttribute(java.lang.String) getStringAttribute}.
+ * {@link #getAttribute(java.lang.String) getAttribute}.
* The following example shows how to list the attributes of an element:
* <UL><CODE>
* XMLElement element = ...;<BR>
- * Enumeration enum = element.getAttributeNames();<BR>
+ * Enumeration enum = element.enumerateAttributeNames();<BR>
* while (enum.hasMoreElements()) {<BR>
* String key = (String) enum.nextElement();<BR>
- * String value = element.getStringAttribute(key);<BR>
+ * String value = (String) element.getAttribute(key);<BR>
* System.out.println(key + " = " + value);<BR>
* }
* </CODE></UL></DD></DL>
diff -r 72471ae86379 plugin/icedteanp/java/sun/applet/PluginAppletViewer.java
--- a/plugin/icedteanp/java/sun/applet/PluginAppletViewer.java Tue Dec 07 15:50:16 2010 -0500
+++ b/plugin/icedteanp/java/sun/applet/PluginAppletViewer.java Tue Dec 07 23:10:34 2010 +0000
@@ -687,7 +687,7 @@
/**
* Function to block until applet initialization is complete
*
- * @param identifier The instance to wait for
+ * @param panel the instance to wait for.
*/
public static void waitForAppletInit(NetxPanel panel) {
More information about the distro-pkg-dev
mailing list