From ef54a0b63c9dccd609adc771c0ec16c5af5b789b Mon Sep 17 00:00:00 2001 From: "Aaron W. Swenson" Date: Tue, 5 Sep 2017 11:35:01 -0400 Subject: Improve documentation Improve documentation to address eclass-to-manpage.sh warnings, and to clean up manpage output. --- postgres-multi.eclass | 29 ++++++++++++++--------------- postgres.eclass | 36 ++++++++++++++++++++++-------------- 2 files changed, 36 insertions(+), 29 deletions(-) diff --git a/postgres-multi.eclass b/postgres-multi.eclass index 9eb7ca2..39f0837 100644 --- a/postgres-multi.eclass +++ b/postgres-multi.eclass @@ -27,7 +27,11 @@ esac # @DESCRIPTION: # A Bash array containing a list of compatible PostgreSQL slots as # defined by the developer. Must be declared before inheriting this -# eclass. Example: POSTGRES_COMPAT=( 9.4 9.{5,6} ) +# eclass. Example: +#@CODE +#POSTGRES_COMPAT=( 9.2 9.3 9.4 9.5 9.6 10 ) +#POSTGRES_COMPAT=( 9.{2,3} 9.{4..6} 10 ) # Same as previous +#@CODE if ! declare -p POSTGRES_COMPAT &>/dev/null; then die 'Required variable POSTGRES_COMPAT not declared.' fi @@ -40,8 +44,8 @@ fi export _POSTGRES_INTERSECT_SLOTS=( ) # @FUNCTION: _postgres-multi_multibuild_wrapper +# @USAGE: [arg ...] # @INTERNAL -# @USAGE: _postgres-multi_multibuild_wrapper [ ...] # @DESCRIPTION: # For the given variant, set the values of the PG_SLOT, PG_CONFIG, and # PKG_CONFIG_PATH environment variables accordingly and replace any @@ -62,16 +66,16 @@ _postgres-multi_multibuild_wrapper() { } # @FUNCTION: postgres-multi_foreach -# @USAGE: postgres-multi_foreach [ ...] +# @USAGE: [arg ...] # @DESCRIPTION: # Run the given command in the package's build directory for each # PostgreSQL slot in the intersect of POSTGRES_TARGETS and -# POSTGRES_COMPAT and user-enabled slots. The PG_CONFIG and -# PKG_CONFIG_PATH environment variables are updated on each iteration to -# point to the matching pg_config command and pkg-config metadata files, -# respectively, for the current slot. Any appearance of @PG_SLOT@ in the -# command or arguments will be substituted with the slot (e.g., 9.5) of -# the current iteration. +# POSTGRES_COMPAT. The PG_CONFIG and PKG_CONFIG_PATH environment +# variables are updated on each iteration to point to the matching +# pg_config command and pkg-config metadata files, respectively, for the +# current slot. Any appearance of @PG_SLOT@ in the command or arguments +# will be substituted with the slot (e.g., 9.5) of the current +# iteration. postgres-multi_foreach() { local MULTIBUILD_VARIANTS=("${_POSTGRES_INTERSECT_SLOTS[@]}") @@ -80,7 +84,7 @@ postgres-multi_foreach() { } # @FUNCTION: postgres-multi_forbest -# @USAGE: postgres-multi_forbest [ ...] +# @USAGE: [arg ...] # @DESCRIPTION: # Run the given command in the package's build directory for the highest # slot in the intersect of POSTGRES_COMPAT and POSTGRES_TARGETS. The @@ -98,7 +102,6 @@ postgres-multi_forbest() { } # @FUNCTION: postgres-multi_pkg_setup -# @USAGE: postgres-multi_pkg_setup # @DESCRIPTION: # Initialize internal environment variable(s). This is required if # pkg_setup() is declared in the ebuild. @@ -119,7 +122,6 @@ postgres-multi_pkg_setup() { } # @FUNCTION: postgres-multi_src_prepare -# @USAGE: postgres-multi_src_prepare # @DESCRIPTION: # Calls eapply_user then copies ${S} into a build directory for each # intersect of POSTGRES_TARGETS and POSTGRES_COMPAT. @@ -152,7 +154,6 @@ postgres-multi_src_prepare() { } # @FUNCTION: postgres-multi_src_compile -# @USAGE: postgres-multi_src_compile # @DESCRIPTION: # Runs `emake' in each build directory postgres-multi_src_compile() { @@ -160,7 +161,6 @@ postgres-multi_src_compile() { } # @FUNCTION: postgres-multi_src_install -# @USAGE: postgres-multi_src_install # @DESCRIPTION: # Runs `emake install DESTDIR="${D}"' in each build directory. postgres-multi_src_install() { @@ -168,7 +168,6 @@ postgres-multi_src_install() { } # @FUNCTION: postgres-multi_src_test -# @USAGE: postgres-multi_src_test # @DESCRIPTION: # Runs `emake installcheck' in each build directory. postgres-multi_src_test() { diff --git a/postgres.eclass b/postgres.eclass index e5a9b6f..2f89da1 100644 --- a/postgres.eclass +++ b/postgres.eclass @@ -35,20 +35,27 @@ _POSTGRES_ALL_VERSIONS=( 11 10 9.6 9.5 9.4 9.3 9.2 ) # @DESCRIPTION: # A Bash array containing a list of compatible PostgreSQL slots as # defined by the developer. If declared, must be declared before -# inheriting this eclass. Example: POSTGRES_COMPAT=( 9.4 9.{5,6} ) - -# @ECLASS-VARIABLE: POSTGRES_USEDEP -# @DEFAULT_UNSET -# @DESCRIPTION: -# Add the 2-Style and/or 4-Style use dependencies without brackets to be used -# for POSTGRES_DEP. If declared, must be done before inheriting this eclass. +# inheriting this eclass. Example: +#@CODE +#POSTGRES_COMPAT=( 9.2 9.3 9.4 9.5 9.6 10 ) +#POSTGRES_COMPAT=( 9.{2,3} 9.{4..6} 10 ) # Same as previous +#@CODE # @ECLASS-VARIABLE: POSTGRES_DEP # @DESCRIPTION: # An automatically generated dependency string suitable for use in # DEPEND and RDEPEND declarations. +POSTGRES_DEP="dev-db/postgresql:=" + +# @ECLASS-VARIABLE: POSTGRES_USEDEP +# @DEFAULT_UNSET +# @DESCRIPTION: +# Add the 2-Style and/or 4-Style use dependencies without brackets to be used +# for POSTGRES_DEP. If declared, must be declared before inheriting this eclass. +declare -p POSTGRES_USEDEP &>/dev/null && POSTGRES_DEP+="[${POSTGRES_USEDEP}]" # @ECLASS-VARIABLE: POSTGRES_REQ_USE +# @DEFAULT_UNSET # @DESCRIPTION: # An automatically generated REQUIRED_USE-compatible string built upon # POSTGRES_COMPAT. REQUIRED_USE="... ${POSTGRES_REQ_USE}" is only @@ -82,10 +89,6 @@ if declare -p POSTGRES_COMPAT &> /dev/null ; then POSTGRES_REQ_USE+=" postgres_targets_postgres${slot/\./_}" done POSTGRES_REQ_USE+=" )" -else - POSTGRES_DEP="dev-db/postgresql:=" - declare -p POSTGRES_USEDEP &>/dev/null && \ - POSTGRES_DEP+="[${POSTGRES_USEDEP}]" fi @@ -113,10 +116,16 @@ postgres_check_slot() { } # @FUNCTION: postgres_new_user +# @USAGE: [user [(uid|-1) [(shell|-1) [(homedir|-1) [groups]]]]] # @DESCRIPTION: # Creates the "postgres" system group and user -- which is separate from -# the database user -- in addition to the developer defined user. Takes -# the same arguments as "enewuser". +# the database user -- and, optionally, the developer defined user. There +# are no required parameters. +# +# When given a user to create, it'll be created with the next available +# uid, default shell set to /bin/false, default homedir is /dev/null, +# and added to the "postgres" system group. You can use "-1" to skip any +# parameter except user or groups. postgres_new_user() { enewgroup postgres 70 enewuser postgres 70 /bin/bash /var/lib/postgresql postgres @@ -133,7 +142,6 @@ postgres_new_user() { } # @FUNCTION: postgres_pkg_setup -# @USAGE: postgres_pkg_setup # @DESCRIPTION: # Initialize environment variable(s) according to the best # installed version of PostgreSQL that is also in POSTGRES_COMPAT. This -- cgit v1.2.3-18-g5258