From 431bc3cd939515331a74bba5729e63de887a0b18 Mon Sep 17 00:00:00 2001 From: Patrice Clement Date: Mon, 19 Oct 2015 14:49:49 +0000 Subject: 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 --- eclass/java-mvn-src.eclass | 55 ++++++++---------- eclass/java-osgi.eclass | 119 ++++++++++++++++++--------------------- eclass/java-pkg-simple.eclass | 128 +++++++++++++++++------------------------- 3 files changed, 127 insertions(+), 175 deletions(-) (limited to 'eclass') 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: +# @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:
+# @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:
+# @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:
+# @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: +# @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: +# @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: +# @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 -# ------------------------------------------------------------------------------ -- cgit v1.2.3-65-gdbad