You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2012/09/25 10:28:54 UTC
svn commit: r1389753 - in /sis/trunk: sis-build-helper/pom.xml
sis-build-helper/src/site/ sis-build-helper/src/site/apt/
sis-build-helper/src/site/apt/index.apt
sis-utility/src/main/java/org/apache/sis/resources/package-info.java
Author: desruisseaux
Date: Tue Sep 25 08:28:53 2012
New Revision: 1389753
URL: http://svn.apache.org/viewvc?rev=1389753&view=rev
Log:
Added documentation.
Added:
sis/trunk/sis-build-helper/src/site/
sis/trunk/sis-build-helper/src/site/apt/
sis/trunk/sis-build-helper/src/site/apt/index.apt
Modified:
sis/trunk/sis-build-helper/pom.xml
sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java
Modified: sis/trunk/sis-build-helper/pom.xml
URL: http://svn.apache.org/viewvc/sis/trunk/sis-build-helper/pom.xml?rev=1389753&r1=1389752&r2=1389753&view=diff
==============================================================================
--- sis/trunk/sis-build-helper/pom.xml (original)
+++ sis/trunk/sis-build-helper/pom.xml Tue Sep 25 08:28:53 2012
@@ -53,11 +53,14 @@
=========================================================== -->
<artifactId>sis-build-helper</artifactId>
<packaging>maven-plugin</packaging>
- <name>Build helper</name>
+ <name>Apache SIS build helper</name>
<description>
- Compiles internationalization files. They are Java properties files transformed
- into UTF files. Their values are made compliant with the java.text.MessageFormat
- syntax, and a set of programmatic constants are generated for the keys.
+ <!-- Left alignment because this description will be copied in META-INF/MANIFEST.MF
+ The leading space after the first line is necessary for proper formatting. -->
+Define Maven Mojos and Javadoc taglets for generating resource files
+ or formatting the Javadoc. While any project could use it, this module
+ is primarily for internal use by Apache SIS and may change in any
+ future version.
</description>
Added: sis/trunk/sis-build-helper/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/sis/trunk/sis-build-helper/src/site/apt/index.apt?rev=1389753&view=auto
==============================================================================
--- sis/trunk/sis-build-helper/src/site/apt/index.apt (added)
+++ sis/trunk/sis-build-helper/src/site/apt/index.apt Tue Sep 25 08:28:53 2012
@@ -0,0 +1,77 @@
+ ------------------------------
+ Index
+ ------------------------------
+
+Building Apache SIS
+
+ The <<<sis-build-helper>>> module defines Maven Mojos and Javadoc taglets for generating
+ resource files or formatting the Javadoc. While any project could use it, this module is
+ primarily for internal use by Apache SIS and may change in any future version.
+
+
+* Javadoc taglets
+
+ This module provides the following javadoc taglets:
+
+ * <<<...@module>>> - replaced in the generated javadoc by a link to the module where the
+ class is defined.
+
+ * <<<{@section}>>> - an inline taglet for the title of a new section in the javadoc.
+
+ * <<<{@note}>>> - an inline taglet for a remark that readers can safely ignore.
+ Notes appear in indented paragraphs with a smaller font.
+
+ * <<<{preformat}>>> - an inline taglet for pre-formatted text. The first word inside
+ the taglet shall be one of <<<java>>>, <<<xml>>>, <<<sql>>>, <<<wkt>>>, <<<text>>>,
+ <<<math>>> or <<<shell>>>.
+
+
+* Localized resources compiler
+
+ Localized resources are provided in <<<*.properties>>> files as specified by the
+ <<<java.util.PropertyResourceBundle>>> standard class. However SIS does not use
+ those resources files directly. Instead <<<*.properties>>> files are transformed
+ into binary files having the same filename but the <<<.utf>>> extension.
+ This conversion is done for efficiency, for convenience (the compiler applies
+ the <<<java.text.MessageFormat>>> <doubled single quotes> rule itself),
+ and for compile-time safety.
+
+ In addition to generating the <<<*.utf>>> files, the resource compiler may modify
+ the <<<*.java>>> files having the same name than the resource files.
+ For example given a set of <<<Vocabulary*.properties>>> files (one for each supported language),
+ the compiler will generate the corresponding <<<Vocabulary*.utf>>> files, then look for a
+ <<<Vocabulary.java>>> source file. If such source file is found and contains a public static
+ inner class named <<<Keys>>>, then the compiler will rewrite the constants declared in that
+ inner class with the list of keys found in the <<<Vocabulary*.properties>>> files.
+
+ The resource compiler is executed at Maven build time when the <<<pom.xml>>> file of a module
+ contains the following declaration. Note that current implementation looks only for resources
+ in the <<<org.apache.sis.resources>>> package; all other packages are ignored.
+
++-----------------------------------------------------
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.sis</groupId>
+ <artifactId>sis-build-helper</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>compile-resources</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
++-----------------------------------------------------
+
+ The resources compilation is part of the build process and does not need to be run explicitly.
+ However, if necessary the resources compiler can be invoked alone by the following command line
+ in the module containing the resources to recompile. This is sometime useful for regenerating
+ the constants in the <<<Keys>>> inner class.
+
++-----------------------------------------------------
+mvn org.apache.sis:sis-build-helper:compile-resources
++-----------------------------------------------------
Modified: sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java
URL: http://svn.apache.org/viewvc/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java?rev=1389753&r1=1389752&r2=1389753&view=diff
==============================================================================
--- sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java (original)
+++ sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java Tue Sep 25 08:28:53 2012
@@ -16,16 +16,36 @@
*/
/**
- * Localized resources for SIS.
+ * Localized resources for SIS. While anyone could use the resources provided in this package,
+ * those resources are primarily for internal SIS usage and may change in any future version.
*
- * <STRONG>Do not use!</STRONG>
+ * <p>Apache SIS resources are provided in binary files having the "{@code .utf}" extension.
+ * The resource keys are numeric constants declared in the {@code Keys} static inner classes.
+ * Values are strings which may optionally have slots for one or more parameters, identified
+ * by the "<code>{</code><var>n</var><code>}</code>" characters sequences where <var>n</var>
+ * is the parameter number (first parameter is "<code>{0}</code>").
+ * If, and only if, a string value has slots for at least one parameter, then:</p>
*
- * This package is for internal use by SIS only. Classes in this package
- * may change in incompatible ways in any future version without notice.
+ * <ul>
+ * <li>the key name ends with the {@code '_'} character followed by the expected number of parameters;</li>
+ * <li>the value string will be compliant with the {@link java.text.MessageFormat} syntax.</li>
+ * </ul>
+ *
+ * <p>Apache SIS developers can add resources by editing the {@code *.properties} file
+ * in the source code directory, then run the localized resources compiler provided in the
+ * <code><a href="{@website}/sis-build-helper/index.html">sis-build-helper</a></code> module.
+ * Developers shall <strong>not</strong> apply the {@code MessageFormat} rules for using quotes,
+ * since the resources compiler will apply itself the <cite>doubled single quotes</cite> when
+ * necessary. This avoid the unfortunate confusion documented in the warning section of
+ * {@link java.text.MessageFormat} javadoc.</p>
*
* @author Martin Desruisseaux (Geomatys)
* @since 0.3 (derived from geotk-1.2)
* @version 0.3
* @module
+ *
+ * @see java.util.ResourceBundle
+ * @see java.text.MessageFormat
+ * @see <a href="{@website}/sis-build-helper/index.html"><code>sis-build-helper</code> module</a>
*/
package org.apache.sis.resources;