Javadoc fixes. One javadoc target documents the public API, another t…

…o check all javadoc including against private methods and test classes. git-svn-id: https://olap4j.svn.sourceforge.net/svnroot/olap4j/trunk@37 c6a108a4-781c-0410-a6c6-c2d559e19af0
ps3331333 · Nov 12, 2007 · fb680a8 · fb680a8
1 parent b066d25
commit fb680a8
Show file tree

Hide file tree

Showing 11 changed files with 128 additions and 76 deletions.
diff --git a/build.xml b/build.xml
@@ -318,15 +318,16 @@ META-INF/**"/>
  <fileset dir="${classes.dir}" includes="**/package.html"/>
  </delete>
  <delete quiet="true" file="${javadoc.dir}/index.html"/>
- <javadoc sourcepath="${src.dir}:${testsrc.dir}"
+ <javadoc sourcepath="${src.dir}"
  classpathref="project.test.classpath"
  destdir="${javadoc.dir}"
- packagenames="org.olap4j.*,mondrian.olap4j.*"
+ packagenames="org.olap4j.*"
+ excludepackagenames="org.olap4j.mdx.parser.impl.*"
  overview="${src.dir}/overview.html"
  footer="&lt;a href=&quot;http://sourceforge.net/projects/olap4j&quot;&gt;&lt;img src=&quot;http://sourceforge.net/sflogo.php?group_id=35302&#38;type=1&quot; width=&quot;88&quot; height=&quot;31&quot; border=&quot;0&quot; alt=&quot;SourceForge.net_Logo&quot;&gt;&lt;/a&gt;"
  author="true"
  source="1.5"
- access="package"
+ access="public"
  Windowtitle="olap4j, version ${version}"
  additionalparam="-linksource"
  >
@@ -338,10 +339,41 @@ META-INF/**"/>
  scope="constructors,methods,types"/>
  <link href="http://java.sun.com/javase/6/docs/api/"/>
  <link href="http://mondrian.pentaho.org/api/"/>
- <link href="http://www.junit.org/junit/javadoc/3.8/"/>
  </javadoc>
  </target>
 
+ <!-- Strict javadoc for testing purposes. Includes all packages and
+ non-public classes and methods. -->
+ <target name="javadoc-strict">
+ <mkdir dir="${javadoc.dir}" />
+ <!-- remove stray package.html files under classes to avoid 'multiple
+ sources of package comments' errors -->
+ <delete includeEmptyDirs="false" quiet="true">
+ <fileset dir="${classes.dir}" includes="**/package.html"/>
+ </delete>
+ <delete quiet="true" file="${javadoc.dir}/index.html"/>
+ <javadoc sourcepath="${src.dir}:${testsrc.dir}"
+ classpathref="project.test.classpath"
+ destdir="${javadoc.dir}"
+ packagenames="org.olap4j.*,mondrian.olap4j.*"
+ overview="${src.dir}/overview.html"
+ footer="&lt;a href=&quot;http://sourceforge.net/projects/olap4j&quot;&gt;&lt;img src=&quot;http://sourceforge.net/sflogo.php?group_id=35302&#38;type=1&quot; width=&quot;88&quot; height=&quot;31&quot; border=&quot;0&quot; alt=&quot;SourceForge.net_Logo&quot;&gt;&lt;/a&gt;"
+ author="true"
+ source="1.5"
+ access="private"
+ Windowtitle="olap4j, version ${version}"
+ >
+ <tag name="pre" description="Pre-condition:"
+ scope="constructors,methods"/>
+ <tag name="post" description="Post-condition:"
+ scope="constructors,methods"/>
+ <tag name="testcase" description="Test-case:"
+ scope="constructors,methods,types"/>
+ <link href="http://java.sun.com/javase/6/docs/api/"/>
+ <link href="http://mondrian.pentaho.org/api/"/>
+ </javadoc>
+ </target>
+
  <!-- Generate javadoc with embedded UML diagrams using the yDoc doclet from
  yWorks.com. Set ydoc.home in build.properties, then replace
  ${ydoc.home}/resources/ydoc.license with a full license (free for open
@@ -399,7 +431,7 @@ META-INF/**"/>
  <delete includeEmptyDirs="false" quiet="true">
  <fileset dir="${classes.dir}" includes="**/package.html"/>
  </delete>
- <javadoc sourcepath="${src.dir}:${testsrc.dir}"
+ <javadoc sourcepath="${src.dir}"
  classpathref="project.test.classpath"
  packagenames="org.olap4j.*"
  excludepackagenames="org.olap4j.sample.*"
@@ -408,12 +440,6 @@ META-INF/**"/>
  source="1.5"
  access="package"
  >
- <!--
- doclet="com.tarsec.javadoc.pdfdoclet.PDFDoclet"
- docletpath="lib/pdfdoclet-1.0.2-all.jar"
- additionalparam="-pdf doc/olap4j_api.pdf -config doc/pdfdoclet.properties"
-
- -->
  <doclet name="com.tarsec.javadoc.pdfdoclet.PDFDoclet"
  path="lib/pdfdoclet-1.0.2-all.jar">
  <param name="-pdf" value="doc/olap4j_api.pdf"/>

diff --git a/doc/deployDoc.sh b/doc/deployDoc.sh
@@ -59,10 +59,10 @@ EOF
 
 else
 
- scp -oPort=8022 dist/doc.tar.gz [email protected]:/home/jhyde
+ scp -oPort=7022 dist/doc.tar.gz [email protected]:/home/jhyde
  GROUP_DIR=/home/jhyde/olap4j
 
- ssh -p 8022 -T [email protected] <<EOF
+ ssh -oPort=7022 -T [email protected] <<EOF
 set -e
 set -v
 cd /home/jhyde

diff --git a/doc/tasks.txt b/doc/tasks.txt
@@ -31,7 +31,6 @@ Javadoc
 -------
 
 * change ant task so it doesn't generate mondrian.olap4j.* or olap4j.test.* or org.olap4j.mdx.parser.impl or package-protected classes (E.g. org.olap4j.mdx.MdxValidator) in public api; remove class OlapTest, class Todo
-* package mdx.parser.impl - comment that this package is not part of the spec, and implementation may change at any time 
 * ensure that every public method has a javadoc description, including @param, @return and @throws declarations 
 * Review olap4j.type package. Document all public methods. Make non-essential methods (E.g. MemberType.forType) package-private. If in doubt, leave it out
 

diff --git a/src/org/olap4j/CellSet.java b/src/org/olap4j/CellSet.java
@@ -93,11 +93,12 @@ public interface CellSet extends ResultSet, OlapWrapper {
  Cell getCell(List<Integer> coordinates);
 
  /**
- * Returns the Cell at a ordinal.
+ * Returns the Cell at an ordinal.
  *
  * <p>Equivalent to
+ *
  * <blockquote><code>
- * getCellFromStar(ordinalToCoordinates(ordinal)
+ * getCell(ordinalToCoordinates(ordinal))
  * </code></blockquote>
  *
  * @param ordinal 0-based ordinal of the cell
@@ -116,7 +117,6 @@ public interface CellSet extends ResultSet, OlapWrapper {
  /**
  * Converts a list of cell coordinates to a cell ordinal.
  *
- * <p>The mapping
  * @param coordinates Cell coordinates
  * @return Cell ordinal
  */

diff --git a/src/org/olap4j/CellSetAxisMetaData.java b/src/org/olap4j/CellSetAxisMetaData.java
@@ -17,21 +17,22 @@
 /**
  * Description of structure of a particular axis of an {@link CellSet}.
  *
- * <p>For example, in the MDX statement
+ * <p>For example, in the MDX statement</p>
+ *
  * <blockquote>
- * <code>
- * SELECT<br/>
- * {[Measures].Members} ON COLUMNS,<br/>
- * CrossJoin([Store].Members, [Gender].Children)<br/>
- * DIMENSION PROPERTIES <br/>
- * MEMBER_ORDINAL,<br/>
- * MEMBER_UNIQUE_NAME, <br/>
- * DISPLAY_INFO ON ROWS<br/>
+ * <pre>
+ * SELECT
+ * {[Measures].Members} ON COLUMNS,
+ * CrossJoin([Store].Members, [Gender].Children)
+ * DIMENSION PROPERTIES
+ * MEMBER_ORDINAL,
+ * MEMBER_UNIQUE_NAME,
+ * DISPLAY_INFO ON ROWS
  * FROM [Sales]
- * </code>
+ * </pre>
  * </blockquote>
  *
- * the ROWS axis is described by the following metadata:
+ * <p>the ROWS axis is described by the following metadata:</p>
  *
  * <table border="1">
  * <tr>

diff --git a/src/org/olap4j/CellSetMetaData.java b/src/org/olap4j/CellSetMetaData.java
@@ -41,17 +41,23 @@
  */
 public interface CellSetMetaData extends ResultSetMetaData, OlapWrapper {
  /**
- * Returns a list of properties which each Cell may have.
+ * Returns a list of Property objects which each Cell may have.
+ *
+ * @return list of cell properties
  */
  List<Property> getCellProperties();
 
  /**
  * Returns the Cube which was referenced in this statement.
+ *
+ * @return cube referenced in this statement
  */
  Cube getCube();
 
  /**
- * Returns a list of metadata describing each result axis.
+ * Returns a list of CellSetAxisMetaData describing each result axis.
+ *
+ * @return list of metadata describing each result axis
  */
  List<CellSetAxisMetaData> getAxesMetaData();
 }

diff --git a/src/org/olap4j/OlapConnection.java b/src/org/olap4j/OlapConnection.java
@@ -26,24 +26,44 @@
 public interface OlapConnection extends Connection, OlapWrapper {
 
  // overrides Connection, with refined return type and throws list
+ /**
+ * {@inheritDoc}
+ * @throws OlapException if database error occurs
+ */
  OlapDatabaseMetaData getMetaData() throws OlapException;
 
  /**
  * Creates a prepared OLAP Statement.
+ *
+ * <p>This method is the equivalent, for OLAP, of the
+ * {@link Connection#prepareStatement(String)} JDBC method.</p>
+ *
+ * @param mdx MDX query string
+ * @return prepared statement
+ * @throws OlapException if database error occurs
  */
  PreparedOlapStatement prepareOlapStatement(String mdx) throws OlapException;
 
  /**
  * Returns the factory used to create MDX parsers in this connection.
+ *
+ * @return MDX parser factory
  */
  MdxParserFactory getParserFactory();
 
  // overrides Connection, with refined return type and throws list
+ /**
+ * {@inheritDoc}
+ * @throws OlapException if database error occurs
+ */
  OlapStatement createStatement() throws OlapException;
 
  /**
  * Returns the current {@link org.olap4j.metadata.Schema} of this
  * connection.
+ *
+ * @return current Schema
+ * @throws OlapException if database error occurs
  */
  Schema getSchema() throws OlapException;
 

diff --git a/src/org/olap4j/OlapDatabaseMetaData.java b/src/org/olap4j/OlapDatabaseMetaData.java
@@ -33,10 +33,13 @@
 public interface OlapDatabaseMetaData extends DatabaseMetaData, OlapWrapper {
 
  // override return type
+ /**
+ * {@inheritDoc}
+ */
  OlapConnection getConnection() throws SQLException;
 
  /**
- * Retrieves a list of descriptions of an Action.
+ * Retrieves a result set describing the Actions in this database.
  *
  * <p>Specification as for XML/A MDSCHEMA_ACTIONS schema rowset.
  *
@@ -206,7 +209,7 @@ ResultSet getDatabaseProperties(
  String propertyNamePattern) throws OlapException;
 
  /**
- * Retrieves a list of descriptions of member and cell Properties.
+ * Retrieves a result set describing member and cell Properties.
  *
  * <p>Specification as for XML/A MDSCHEMA_PROPERTIES schema rowset.
  *
@@ -285,6 +288,7 @@ ResultSet getDatabaseProperties(
  * @exception OlapException if a database access error occurs
  *
  * @see #getSearchStringEscape
+ * @see org.olap4j.metadata.Property
  */
  ResultSet getProperties(
  String catalog,
@@ -306,7 +310,7 @@ ResultSet getProperties(
  String getMdxKeywords() throws OlapException;
 
  /**
- * Retrieves a description of a cube.
+ * Retrieves a result set describing the Cubes in this database.
  *
  * <p>Specification as for XML/A MDSCHEMA_CUBES schema rowset.
  *
@@ -360,15 +364,16 @@ ResultSet getProperties(
  * @exception OlapException if a database access error occurs
  *
  * @see #getSearchStringEscape
+ * @see org.olap4j.metadata.Cube
  */
  public ResultSet getCubes(
  String catalog,
  String schemaPattern,
  String cubeNamePattern) throws OlapException;
 
  /**
- * Retrieves a result set describing the shared and private dimensions
- * within a database.
+ * Retrieves a result set describing the shared and private Dimensions
+ * in this database.
  *
  * <p>Specification as for XML/A MDSCHEMA_DIMENSIONS schema rowset.
  *
@@ -435,6 +440,7 @@ public ResultSet getCubes(
  * @exception OlapException if a database access error occurs
  *
  * @see #getSearchStringEscape
+ * @see org.olap4j.metadata.Dimension
  */
  ResultSet getDimensions(
  String catalog,
@@ -443,7 +449,7 @@ ResultSet getDimensions(
  String dimensionNamePattern) throws OlapException;
 
  /**
- * Retrieves a result set describing the functions available to client
+ * Retrieves a result set describing the Functions available to client
  * applications connected to the database.
  *
  * <p>Specification as for XML/A MDSCHEMA_FUNCTIONS schema rowset.
@@ -484,8 +490,7 @@ ResultSet getOlapFunctions(
  String functionNamePattern) throws OlapException;
 
  /**
- * Retrieves a result set describing each hierarchy within a particular
- * dimension.
+ * Retrieves a result set describing the Hierarchies in this database.
  *
  * <p>Specification as for XML/A MDSCHEMA_HIERARCHIES schema rowset.
  *
@@ -561,6 +566,7 @@ ResultSet getOlapFunctions(
  * @exception OlapException if a database access error occurs
  *
  * @see #getSearchStringEscape
+ * @see org.olap4j.metadata.Hierarchy
  */
  ResultSet getHierarchies(
  String catalog,
@@ -570,8 +576,7 @@ ResultSet getHierarchies(
  String hierarchyNamePattern) throws OlapException;
 
  /**
- * Retrieves a result set describing each level within a particular
- * hierarchy.
+ * Retrieves a result set describing the Levels in this database.
  *
  * <p>Specification as for XML/A MDSCHEMA_LEVELS schema rowset.
  *
@@ -650,6 +655,7 @@ ResultSet getHierarchies(
  * @exception OlapException if a database access error occurs
  *
  * @see #getSearchStringEscape
+ * @see org.olap4j.metadata.Level
  */
  ResultSet getLevels(
  String catalog,
@@ -660,7 +666,7 @@ ResultSet getLevels(
  String levelNamePattern) throws OlapException;
 
  /**
- * Retrieves a result set describing each measure within a cube.
+ * Retrieves a result set describing the Measures in this database.
  *
  * <p>Specification as for XML/A MDSCHEMA_MEASURES schema rowset.
  *
@@ -721,6 +727,7 @@ ResultSet getLevels(
  * @exception OlapException if a database access error occurs
  *
  * @see #getSearchStringEscape
+ * @see org.olap4j.metadata.Measure
  */
  ResultSet getMeasures(
  String catalog,
@@ -730,7 +737,7 @@ ResultSet getMeasures(
  String measureUniqueName) throws OlapException;
 
  /**
- * Retrieves a result set describing the members within a database.
+ * Retrieves a result set describing the Members in this database.
  *
  * <p>Specification as for XML/A MDSCHEMA_MEMBERS schema rowset.
  *
@@ -839,6 +846,7 @@ ResultSet getMeasures(
  * @exception OlapException if a database access error occurs
  *
  * @see #getSearchStringEscape
+ * @see org.olap4j.metadata.Member
  */
  ResultSet getMembers(
  String catalog,
@@ -851,7 +859,7 @@ ResultSet getMembers(
  Set<Member.TreeOp> treeOps) throws OlapException;
 
  /**
- * Retrieves a result set describing each named set.
+ * Retrieves a result set describing the named Sets in this database.
  *
  * <p>Specification as for XML/A MDSCHEMA_SETS schema rowset.
  *
@@ -889,6 +897,7 @@ ResultSet getMembers(
  * @exception OlapException if a database access error occurs
  *
  * @see #getSearchStringEscape
+ * @see org.olap4j.metadata.NamedSet
  */
  ResultSet getSets(
  String catalog,