Merge remote-tracking branch 'github/pr/264'.

3 files changed, 127 insertions, 175 deletions

diff --git a/eclass/java-mvn-src.eclass b/eclass/java-mvn-src.eclass
index c34034eb00d7..a7f8e5bc2fa5 100644
--- a/eclass/java-mvn-src.eclass
+++ b/eclass/java-mvn-src.eclass
@@ -2,12 +2,13 @@
 # Distributed under the terms of the GNU General Public License v2
 # $Id$
 
-inherit java-pkg-simple
-
-# -----------------------------------------------------------------------------
-# @eclass-begin
-# @eclass-summary Eclass for Java packages from bare sources exported by Maven
-#
+# @ECLASS: java-mvn-src.eclass
+# @MAINTAINER:
+# java@gentoo.org
+# @AUTHOR:
+# Java maintainers (java@gentoo.org)
+# @BLURB: Eclass for Java packages from bare sources exported by Maven
+# @DESCRIPTION:
 # This class is intended to build pure Java packages from the sources exported
 # from the source:jar goal of Maven 2. These archives contain bare Java source
 # files, with no build instructions or additional resource files. They are
@@ -16,38 +17,30 @@ inherit java-pkg-simple
 # are often released together with binary packages, whereas the full build
 # environment might be contained in some revision control system or not
 # available at all.
-# -----------------------------------------------------------------------------
-
-# -----------------------------------------------------------------------------
-# @variable-external GROUP_ID
-# @variable-default ${PN}
-#
-# The groupId of the artifact, in dotted notation.
-# -----------------------------------------------------------------------------
+
+inherit java-pkg-simple
+
+# @ECLASS-VARIABLE: GROUP_ID
+# @DESCRIPTION:
+# The groupId of the artifact, in dotted notation. Default value is ${PN}.
 : ${GROUP_ID:=${PN}}
 
-# -----------------------------------------------------------------------------
-# @variable-external ARTIFACT_ID
-# @variable-default ${PN}
-#
-# The artifactId of the artifact.
-# -----------------------------------------------------------------------------
+# @ECLASS-VARIABLE: ARTIFACT_ID
+# The artifactId of the artifact. Default value is ${PN}.
+
 : ${ARTIFACT_ID:=${PN}}
 
-# -----------------------------------------------------------------------------
-# @variable-external MAVEN2_REPOSITORIES
-# @variable-default http://repo2.maven.org/maven2 http://download.java.net/maven/2
-#
+# @ECLASS-VARIABLE: MAVEN2_REPOSITORIES
+# @DESCRIPTION:
 # The repositories to search for the artifacts. Must follow Maven2 layout.
-# -----------------------------------------------------------------------------
+# Default value is the following string:
+# "http://repo2.maven.org/maven2 http://download.java.net/maven/2"
 : ${MAVEN2_REPOSITORIES:="http://repo2.maven.org/maven2 http://download.java.net/maven/2"}
 
-# -----------------------------------------------------------------------------
-# @variable-internal RELATIVE_SRC_URI
-#
+# @ECLASS-VARIABLE: RELATIVE_SRC_URI
+# @DESCRIPTION:
 # The path of the source artifact relative to the root of the repository.
 # Will be set by the eclass to follow Maven 2 repository layout.
-# -----------------------------------------------------------------------------
 RELATIVE_SRC_URI=${GROUP_ID//./\/}/${ARTIFACT_ID}/${PV}/${ARTIFACT_ID}-${PV}-sources.jar
 
 # Look for source jar in all listed repositories
@@ -55,7 +48,3 @@ for repo in ${MAVEN2_REPOSITORIES}; do
 	SRC_URI="${SRC_URI} ${repo}/${RELATIVE_SRC_URI}"
 done
 unset repo
-
-# ------------------------------------------------------------------------------
-# @eclass-end
-# ------------------------------------------------------------------------------
diff --git a/eclass/java-osgi.eclass b/eclass/java-osgi.eclass
index 46865fa8b1ce..62f3046445a8 100644
--- a/eclass/java-osgi.eclass
+++ b/eclass/java-osgi.eclass
@@ -2,26 +2,26 @@
 # Distributed under the terms of the GNU General Public License v2
 # $Id$
 
-# -----------------------------------------------------------------------------
-# @eclass-begin
-# @eclass-shortdesc Java OSGi eclass
-# @eclass-maintainer java@gentoo.org
-#
-# This eclass provides functionality which is used by
-# packages that need to be OSGi compliant. This means
-# that the generated jars will have special headers in their manifests.
-# Currently this is used only by Eclipse-3.3 - later
-# we could extend this so that Gentoo Java system would be
-# fully OSGi compliant.
-#
-# -----------------------------------------------------------------------------
+# @ECLASS: java-osgi.eclass
+# @MAINTAINER:
+# java@gentoo.org
+# @AUTHOR:
+# Java maintainers (java@gentoo.org)
+# @BLURB: Java OSGi eclass
+# @DESCRIPTION:
+# This eclass provides functionality which is used by packages that need to be
+# OSGi compliant. This means that the generated jars will have special headers
+# in their manifests. Currently this is used only by Eclipse-3.3 - later we
+# could extend this so that Gentoo Java system would be fully OSGi compliant.
 
 inherit java-utils-2
 
+# @ECLASS-VARIABLE: _OSGI_T
+# @INTERNAL
+# @DESCRIPTION:
 # We define _OSGI_T so that it does not contain a slash at the end.
 # According to Paludis guys, there is currently a proposal for EAPIs that
 # would require all variables to end with a slash.
-
 _OSGI_T="${T/%\//}"
 
 # must get Diego to commit something like this to portability.eclass
@@ -36,18 +36,17 @@ _canonicalise() {
 	fi
 }
 
-# -----------------------------------------------------------------------------
-# @ebuild-function _java-osgi_plugin
-#
+# @FUNCTION: _java-osgi_plugin
+# @USAGE: <plugin name>
+# @INTERNAL
+# @DESCRIPTION:
 # This is an internal function, not to be called directly.
 #
-# @example
+# @CODE
 #	_java-osgi_plugin "JSch"
+# @CODE
 #
 # @param $1 - bundle name
-#
-# ------------------------------------------------------------------------------
-
 _java-osgi_plugin() {
 	# We hardcode Gentoo as the vendor name
 
@@ -57,21 +56,20 @@ _java-osgi_plugin() {
 	EOF
 }
 
-# -----------------------------------------------------------------------------
-# @ebuild-function _java-osgi_makejar
-#
+# @FUNCTION: _java-osgi_makejar
+# @USAGE: <jar name> <symbolic name> <bundle name> <header name>
+# @INTERNAL
+# @DESCRIPTION:
 # This is an internal function, not to be called directly.
 #
-# @example
+# @CODE
 #	_java-osgi_makejar "dist/${PN}.jar" "com.jcraft.jsch" "JSch" "com.jcraft.jsch, com.jcraft.jsch.jce;x-internal:=true"
+# @CODE
 #
 # @param $1 - name of jar to repackage with OSGi
 # @param $2 - bundle symbolic name
 # @param $3 - bundle name
 # @param $4 - export-package header
-#
-# ------------------------------------------------------------------------------
-
 _java-osgi_makejar() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -104,9 +102,9 @@ _java-osgi_makejar() {
 	rm -rf "${_OSGI_T}/tmp_jar"
 }
 
-# -----------------------------------------------------------------------------
-# @ebuild-function java-osgi_dojar
-#
+# @FUNCTION: @java-osgi_dojar
+# @USAGE: <jar name> <symbolic name> <bundle name> <header name>
+# @DESCRIPTION:
 # Rewrites a jar, and produce an OSGi compliant jar from arguments given on the command line.
 # The arguments given correspond to the minimal set of headers
 # that must be present on a Manifest file of an OSGi package.
@@ -114,16 +112,14 @@ _java-osgi_makejar() {
 # that create the Manifest from a file.
 # It will call java-pkg_dojar at the end.
 #
-# @example
+# @CODE
 #	java-osgi_dojar "dist/${PN}.jar" "com.jcraft.jsch" "JSch" "com.jcraft.jsch, com.jcraft.jsch.jce;x-internal:=true"
+# @CODE
 #
 # @param $1 - name of jar to repackage with OSGi
 # @param $2 - bundle symbolic name
 # @param $3 - bundle name
 # @param $4 - export-package-header
-#
-# ------------------------------------------------------------------------------
-
 java-osgi_dojar() {
 	debug-print-function ${FUNCNAME} "$@"
 	local jarName="$(basename ${1})"
@@ -131,9 +127,9 @@ java-osgi_dojar() {
 	java-pkg_dojar "${_OSGI_T}/osgi/${jarName}"
 }
 
-# -----------------------------------------------------------------------------
-# @ebuild-function java-osgi_newjar
-#
+# @FUNCTION: java-osgi_newjar
+# @USAGE: <jar name> <symbolic name> <bundle name> <header name>
+# @DESCRIPTION:
 # Rewrites a jar, and produce an OSGi compliant jar.
 # The arguments given correspond to the minimal set of headers
 # that must be present on a Manifest file of an OSGi package.
@@ -141,17 +137,15 @@ java-osgi_dojar() {
 # that create the Manifest from a file.
 # It will call java-pkg_newjar at the end.
 #
-# @example
+# @CODE
 #	java-osgi_newjar "dist/${PN}.jar" "com.jcraft.jsch" "JSch" "com.jcraft.jsch, com.jcraft.jsch.jce;x-internal:=true"
+# @CODE
 #
 # @param $1 - name of jar to repackage with OSGi
 # @param $2 (optional) - name of the target jar. It will default to package name if not specified.
 # @param $3 - bundle symbolic name
 # @param $4 - bundle name
 # @param $5 - export-package header
-#
-# ------------------------------------------------------------------------------
-
 java-osgi_newjar() {
 	debug-print-function ${FUNCNAME} "$@"
 	local jarName="$(basename $1)"
@@ -165,21 +159,20 @@ java-osgi_newjar() {
 	fi
 }
 
-# -----------------------------------------------------------------------------
-# @ebuild-function _java-osgi_makejar-fromfile
-#
+# @FUNCTION:_java-osgi_makejar-fromfile
+# @USAGE: <jar to repackage with OSGi> <Manifest file> <bundle name> <version rewriting>
+# @INTERNAL
+# @DESCRIPTION:
 # This is an internal function, not to be called directly.
 #
-# @example
+# @CODE
 #	_java-osgi_makejar-fromfile "dist/${PN}.jar" "${FILESDIR}/MANIFEST.MF" "JSch" 1
+# @CODE
 #
 # @param $1 - name of jar to repackage with OSGi
 # @param $2 - path to the Manifest file
 # @param $3 - bundle name
 # @param $4 - automatic version rewriting (0 or 1)
-#
-# ------------------------------------------------------------------------------
-
 _java-osgi_makejar-fromfile() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -212,27 +205,26 @@ _java-osgi_makejar-fromfile() {
 	rm -rf "${_OSGI_T}/tmp_jar"
 }
 
-# -----------------------------------------------------------------------------
-# @ebuild-function java-osgi_newjar-fromfile()
-#
+# @FUNCTION: java-osgi_newjar-fromfile
+# @USAGE: <jar to repackage with OSGi> <Manifest file> <bundle name> <version rewriting>
+# @DESCRIPTION:
 # This function produces an OSGi compliant jar from a given manifest file.
 # The Manifest Bundle-Version header will be replaced by the current version
 # of the package, unless the --no-auto-version option is given.
 # It will call java-pkg_newjar at the end.
 #
-# @example
+# @CODE
 #	java-osgi_newjar-fromfile "dist/${PN}.jar" "${FILESDIR}/MANIFEST.MF" "Standard Widget Toolkit for GTK 2.0"
+# @CODE
 #
 # @param $opt
 #	--no-auto-version - This option disables automatic rewriting of the
-#		version in the Manifest file#
+#		version in the Manifest file
+#
 # @param $1 - name of jar to repackage with OSGi
 # @param $2 (optional) - name of the target jar. It will default to package name if not specified.
 # @param $3 - path to the Manifest file
 # @param $4 - bundle name
-#
-# ------------------------------------------------------------------------------
-
 java-osgi_newjar-fromfile() {
 	debug-print-function ${FUNCNAME} "$@"
 	local versionRewriting=1
@@ -252,26 +244,25 @@ java-osgi_newjar-fromfile() {
 	fi
 }
 
-# -----------------------------------------------------------------------------
-# @ebuild-function java-osgi_dojar-fromfile()
-#
+# @FUNCTION: java-osgi_dojar-fromfile()
+# @USAGE: <jar to repackage with OSGi> <Manifest file> <bundle name>
+# @DESCRIPTION:
 # This function produces an OSGi compliant jar from a given manifestfile.
 # The Manifest Bundle-Version header will be replaced by the current version
 # of the package, unless the --no-auto-version option is given.
 # It will call java-pkg_dojar at the end.
 #
-# @example
+# @CODE
 #	java-osgi_dojar-fromfile "dist/${PN}.jar" "${FILESDIR}/MANIFEST.MF" "Standard Widget Toolkit for GTK 2.0"
+# @CODE
 #
 # @param $opt
 #	--no-auto-version - This option disables automatic rewriting of the
 #		version in the Manifest file
+#
 # @param $1 - name of jar to repackage with OSGi
 # @param $2 - path to the Manifest file
 # @param $3 - bundle name
-#
-# ------------------------------------------------------------------------------
-
 java-osgi_dojar-fromfile() {
 	debug-print-function ${FUNCNAME} "$@"
 	local versionRewriting=1
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
-# ------------------------------------------------------------------------------