sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject 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
Date Tue, 25 Sep 2012 08:28:54 GMT
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;



Mime
View raw message