java-{mvn-src,osgi,pkg-simple}.eclass: Rewrite documentation to make it compliant with the new style. Fixes bug 476946.

Signed-off-by: Patrice Clement <monsieurp@gentoo.org>

1 files changed, 50 insertions, 78 deletions

diff --git a/eclass/java-pkg-simple.eclass b/eclass/java-pkg-simple.eclass
index 7abdb624de5e..c06bb11504a0 100644
--- a/eclass/java-pkg-simple.eclass
+++ b/eclass/java-pkg-simple.eclass
@@ -2,16 +2,13 @@
 # Distributed under the terms of the GNU General Public License v2
 # $Id$
 
-inherit java-utils-2
-
-if ! has java-pkg-2 ${INHERITED}; then
-	eerror "java-pkg-simple eclass can only be inherited AFTER java-pkg-2"
-fi
-
-# -----------------------------------------------------------------------------
-# @eclass-begin
-# @eclass-summary Eclass for Java sources without build instructions
-#
+# @ECLASS: java-pkg-simple.eclass
+# @MAINTAINER:
+# java@gentoo.org
+# @AUTHOR:
+# Java maintainers (java@gentoo.org)
+# @BLURB: Eclass for packaging Java software with ease.
+# @DESCRIPTION:
 # This class is intended to build pure Java packages from Java sources
 # without the use of any build instructions shipped with the sources.
 # There is no support for resources besides the generated class files,
@@ -19,92 +16,75 @@ fi
 # the resulting jar, although these issues may be addressed by an
 # ebuild by putting corresponding files into the target directory
 # before calling the src_compile function of this eclass.
-# -----------------------------------------------------------------------------
+
+inherit java-utils-2
+
+if ! has java-pkg-2 ${INHERITED}; then
+	eerror "java-pkg-simple eclass can only be inherited AFTER java-pkg-2"
+fi
 
 EXPORT_FUNCTIONS src_compile src_install
 
 # We are only interested in finding all java source files, wherever they may be.
 S="${WORKDIR}"
 
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_GENTOO_CLASSPATH
-# @variable-default ""
-#
+# @ECLASS-VARIABLE: JAVA_GENTOO_CLASSPATH
+# @DEFAULT_UNSET
+# @DESCRIPTION:
 # Comma or space separated list of java packages to include in the
 # class path. The packages will also be registered as runtime
 # dependencies of this new package. Dependencies will be calculated
 # transitively. See "java-config -l" for appropriate package names.
-# -----------------------------------------------------------------------------
-# JAVA_GENTOO_CLASSPATH
-
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_CLASSPATH_EXTRA
-# @variable-default ""
 #
+# @CODE
+#	JAVA_GENTOO_CLASSPATH="foo,bar-2"
+# @CODE
+
+# @ECLASS-VARIABLE: JAVA_CLASSPATH_EXTRA
+# @DEFAULT_UNSET
+# @DESCRIPTION:
 # Extra list of colon separated path elements to be put on the
 # classpath when compiling sources.
-# -----------------------------------------------------------------------------
-# JAVA_CLASSPATH_EXTRA
 
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_SRC_DIR
-# @variable-default ""
-#
+# @ECLASS-VARIABLE: JAVA_SRC_DIR
+# @DEFAULT_UNSET
+# @DESCRIPTION:
 # Directories relative to ${S} which contain the sources of the
 # application. The default of "" will be treated mostly as ${S}
 # itself. For the generated source package (if source is listed in
 # ${JAVA_PKG_IUSE}), it is important that these directories are
 # actually the roots of the corresponding source trees.
-# -----------------------------------------------------------------------------
-# JAVA_SRC_DIR
-
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_ENCODING
-# @variable-default UTF-8
 #
-# The character encoding used in the source files
-# -----------------------------------------------------------------------------
+# @CODE
+#	JAVA_SRC_DIR="src/java/org/gentoo"
+# @CODE
+
+# @ECLASS-VARIABLE: JAVA_SRC_DIR
+# @DESCRIPTION:
+# The character encoding used in the source files.
 : ${JAVA_ENCODING:=UTF-8}
 
-# -----------------------------------------------------------------------------
-# @variable-external JAVAC_ARGS
-# @variable-default ""
-#
-# Additional arguments to be passed to javac
-# -----------------------------------------------------------------------------
-# JAVAC_ARGS
+# @ECLASS-VARIABLE: JAVAC_ARGS
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Additional arguments to be passed to javac.
 
-# -----------------------------------------------------------------------------
-# @variable-external JAVADOC_ARGS
-# @variable-default ""
-#
-# Additional arguments to be passed to javadoc
-# -----------------------------------------------------------------------------
-# JAVADOC_ARGS
+# @ECLASS-VARIABLE: JAVADOC_ARGS
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Additional arguments to be passed to javadoc.
 
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_JAR_FILENAME
-# @variable-default ${PN}.jar
-#
-# The name of the jar file to create and install
-# -----------------------------------------------------------------------------
+# @ECLASS-VARIABLE: JAVA_JAR_FILENAME
+# @DESCRIPTION:
+# The name of the jar file to create and install.
 : ${JAVA_JAR_FILENAME:=${PN}.jar}
 
-# ------------------------------------------------------------------------------
-# @eclass-src_compile
-#
+# @FUNCTION: java-pkg-simple_src_compile
+# @DESCRIPTION:
 # src_compile for simple bare source java packages. Finds all *.java
 # sources in ${JAVA_SRC_DIR}, compiles them with the classpath
 # calculated from ${JAVA_GENTOO_CLASSPATH}, and packages the resulting
 # classes to ${JAVA_JAR_FILENAME}.
-#
-# variables:
-# JAVA_GENTOO_CLASSPATH - list java packages to put on the classpath.
-# JAVA_ENCODING - encoding of source files, used by javac and javadoc
-# JAVA_SRC_DIR - directories containing source files, relative to ${S}
-# JAVAC_ARGS - additional arguments to be passed to javac
-# JAVADOC_ARGS - additional arguments to be passed to javadoc
-# ------------------------------------------------------------------------------
 java-pkg-simple_src_compile() {
 	local sources=sources.lst classes=target/classes apidoc=target/api
 
@@ -146,14 +126,12 @@ java-pkg-simple_src_compile() {
 		jar ${jar_args} -C ${classes} . || die "jar failed"
 }
 
-# ------------------------------------------------------------------------------
-# @eclass-src_install
-#
+# @FUNCTION: java-pkg-simple_src_install
+# @DESCRIPTION:
 # src_install for simple single jar java packages. Simply packages the
 # contents from the target directory and installs it as
 # ${JAVA_JAR_FILENAME}. If the file target/META-INF/MANIFEST.MF exists,
 # it is used as the manifest of the created jar.
-# ------------------------------------------------------------------------------
 java-pkg-simple_src_install() {
 	local sources=sources.lst classes=target/classes apidoc=target/api
 
@@ -186,20 +164,14 @@ java-pkg-simple_src_install() {
 	fi
 }
 
-# ------------------------------------------------------------------------------
-# @internal-function java-pkg-simple_verbose-cmd
-#
+# @FUNCTION: java-pkg-simple_src_install
+# @DESCRIPTION:
 # Print a command before executing it. To give user some feedback
 # about what is going on, where the time is being spent, and also to
 # help debugging ebuilds.
 #
 # @param $@ - command to be called and its arguments
-# ------------------------------------------------------------------------------
 java-pkg-simple_verbose-cmd() {
 	echo "$*"
 	"$@"
 }
-
-# ------------------------------------------------------------------------------
-# @eclass-end
-# ------------------------------------------------------------------------------