Expanded inline documentation

* Changed code example as suggested in
https://forums.gentoo.org/viewtopic-t-1129590.html
* Added installation instructions

README.md

@@ -1,16 +1,16 @@
-This repo contains an eclass that may be used to verify the signature on the top commit of a repository checked out during `git-r3` based installation.
+This repo contains an eclass that may be used to verify the signature on the top commit of a repository checked out during `git-r3` based ebuild installation.
 
-git-verify-signature.eclass is based on [`verify-sig.eclass`](https://gitweb.gentoo.org/repo/gentoo.git/tree/eclass/verify-sig.eclass).
+git-verify-signature.eclass is based on  and exposes the same variables.
 
 # Usage
 
-This eclass relies on same variables as `verify-sig` eclass. The simplest use case is installing a live ebuild. To verify the signature, add the following to your ebuild:
+This eclass relies on same variables as [`verify-sig.eclass`](https://gitweb.gentoo.org/repo/gentoo.git/tree/eclass/verify-sig.eclass) eclass. The simplest use case is installing a live ebuild. To verify the signature, add the following to your ebuild:
 
 * Add `inherit git-verify-signature`
 * Specify the key location in `VERIFY_SIG_OPENPGP_KEY_PATH`
 * Add BDEPEND dependency to the openpgp-key ebuild
 
-When a user would be installing that ebuild with `verify-sig` useflag, the default `src-unpack` from `git-verify-signature.eclass` will run the `git-r3.eclass`'s standard `src_unpack` and verify the top signature.
+When a user would be installing that ebuild with `verify-sig` useflag enabled, the default `src-unpack` from `git-verify-signature.eclass` will run the `git-r3.eclass`'s standard `src_unpack` and verify the signature on top commit.
 
 The function to verify the signature is available separately as `git-verify-signature_verify-commit` in case non-default `src_unpack` is needed.
 
@@ -20,21 +20,10 @@ Also see the code example inside the eclass.
 
 # Installation
 
-To use this eclass in your overlay, add as a submodule to your overlay if using git and copy the git-verify-signature.eclass file to `eclass` directory.
+Download the [latest release from GitHub](https://github.com/VTimofeenko/git-verify-signature.eclass/releases) and copy the `
+git-verify-signature.eclass` file to your overlay's eclass directory.
 
-1. From the root directory of overlay, create `submodules`:
-
-        # mkdir submodules
-
-2. Add this repo as submodule:
-
-        # git submodule add https://github.com/VTimofeenko/git-verify-signature.eclass submodules/git-verify-signature.eclass
-
-3. Copy the file to eclass directory:
-
-        # cp submodules/git-verify-signature.eclass/git-verify-signature.eclass eclass/
-
-    **Note**: a symlink is not the best solution here, because at the time of writing `emerge --sync` and `emaint sync` do not retrieve submodules for overlays.
+Alternatively, install the latest `app-portage/git-verify-signature` from [nitratesky overlay](https://github.com/VTimofeenko/nitratesky) and copy the file from ebuild's message.
 
 # Example
 

git-verify-signature.eclass

@@ -6,7 +6,7 @@
 # Vladimir Timofeenko <[email protected]>
 # @AUTHOR:
 # Vladimir Timofeenko <[email protected]>
-# @BLURB: Allows verifying signature on top commit
+# @BLURB: Allows verifying signature on top commit of a git repository
 # @DESCRIPTION:
 # This eclass provides the ability to verify the signature on the
 # top commit of repository checked out by git-r3.
@@ -19,8 +19,9 @@
 # Example use:
 # @CODE
 # inherit git-verify-signature
-# SRC_URI="https://example.org/${P}.tar.gz
-#   verify-sig? ( https://example.org/${P}.tar.gz.sig )"
+# EGIT_REPO_URI="https://example.org/author/repository.git"
+# EGIT_BRANCH="some-non-default-branch"
+# EGIT_COMMIT="some-commit-or-tag"
 # BDEPEND="
 #   verify-sig? ( app-crypt/openpgp-keys-example )"
 #
@@ -33,7 +34,11 @@
 # specifying the directory where to verify the commit.
 #
 # Some notes:
-# inherit verify-sig is used to properly add the dependencies
+# * inherit verify-sig is used to properly add the DEPENDs
+# * At the time of writing (Feb 12, 2021) there are no usages of git-r3
+# with verify-sig eclasses in the same ebuild in the main tree.
+# In case the interface this class provides collides with verify-sig
+# behavior, send the author a note.
 
 if [[ ! ${_GIT_VERIFY_SIG_ECLASS} ]]; then
 
@@ -52,8 +57,35 @@ EXPORT_FUNCTIONS src_unpack
 
 inherit git-r3 verify-sig
 
-# @FUNCTION: git-verify-signature_src_unpack
+# Variables from verify-sig.eclass
+# @ECLASS-VARIABLE: VERIFY_SIG_OPENPGP_KEY_PATH
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Path to key bundle used to perform the verification.  This is required
+# when using default src_unpack.  Alternatively, the key path can be
+# passed directly to the verification functions.
+
+# @ECLASS-VARIABLE: VERIFY_SIG_OPENPGP_KEYSERVER
+# @DEFAULT_UNSET
 # @DESCRIPTION:
+# Keyserver used to refresh keys.  If not specified, the keyserver
+# preference from the key will be respected.  If no preference
+# is specified by the key, the GnuPG default will be used.
+
+# @ECLASS-VARIABLE: VERIFY_SIG_OPENPGP_KEY_REFRESH
+# @USER_VARIABLE
+# @DESCRIPTION:
+# Attempt to refresh keys via WKD/keyserver.  Set it to "yes"
+# in make.conf to enable.  Note that this requires working Internet
+# connection.
+# end of variables from verify-sig.eclass
+
+# @FUNCTION: git-verify-signature_src_unpack
+# @DESCRIPTION: provides the default src_unpack modeled after git-r3's src_unpack
+# If the verify-sig useflag is enabled, verifies the checked out code.
+# If you would like to use a different src_unpack - inherit this eclass before
+# a different eclass. To verify the commit then - use the
+# git-verify-signature_verify_commit function separately
 git-verify-signature_src_unpack() {
 	git-r3_src_unpack
 	if use verify-sig; then