diff --git a/Makefile b/Makefile
index bf81a02e023..7c85d61dd8a 100644
--- a/Makefile
+++ b/Makefile
@@ -325,7 +325,7 @@ validate: validate-source validate-binaries
 # not automated right now.  The hope is that eventually the quay.io/libpod/fedora_podman is multiarch and can replace this
 # image in the future.
 .PHONY: validatepr
-validatepr:
+validatepr: ## Go Format and lint, which all code changes must pass
 	$(PODMANCMD) run --rm \
 		-v $(CURDIR):/go/src/github.com/containers/podman \
 		--security-opt label=disable \
diff --git a/docs/source/markdown/options/secret.image.md b/docs/source/markdown/options/secret.image.md
index a8267801d70..46f8ff0f970 100644
--- a/docs/source/markdown/options/secret.image.md
+++ b/docs/source/markdown/options/secret.image.md
@@ -2,12 +2,22 @@
 ####>   podman build, farm build
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
-#### **--secret**=**id=id,src=path**
+#### **--secret**=**id=id[,src=*envOrFile*][,env=*ENV*][,type=*file* | *env*]**
 
-Pass secret information used in the Containerfile for building images
-in a safe way that are not stored in the final image, or be seen in other stages.
-The secret is mounted in the container at the default location of `/run/secrets/id`.
+Pass secret information to be used in the Containerfile for building images
+in a safe way that will not end up stored in the final image, or be seen in other stages.
+The value of the secret will be read from an environment variable or file named
+by the "id" option, or named by the "src" option if it is specified, or from an
+environment variable specified by the "env" option. See [EXAMPLES](#examples).
+The secret will be mounted in the container at `/run/secrets/id` by default.
 
-To later use the secret, use the --mount option in a `RUN` instruction within a `Containerfile`:
+To later use the secret, use the --mount flag in a `RUN` instruction within a `Containerfile`:
 
 `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`
+
+The location of the secret in the container can be overridden using the
+"target", "dst", or "destination" option of the `RUN --mount` flag.
+
+`RUN --mount=type=secret,id=mysecret,target=/run/secrets/myothersecret cat /run/secrets/myothersecret`
+
+Note: changing the contents of secret files will not trigger a rebuild of layers that use said secrets.
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
index 08c5d3d144e..b7fe733f005 100644
--- a/docs/source/markdown/podman-build.1.md.in
+++ b/docs/source/markdown/podman-build.1.md.in
@@ -566,6 +566,23 @@ Build image using the specified network when running containers during the build
 $ podman build --network mynet .
 ```
 
+Build an image using a secret stored in an environment variable or file named `mysecret` to be used with the instruction `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`:
+```
+$ podman build --secret=id=mysecret .
+```
+
+Build an image using a secret stored in an environment variable named `MYSECRET` to be used with the instruction `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`:
+```
+$ podman build --secret=id=mysecret,env=MYSECRET .
+$ podman build --secret=id=mysecret,src=MYSECRET,type=env .
+```
+
+Build an image using a secret stored in a file named `.mysecret` to be used with the instruction `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`:
+```
+$ podman build --secret=id=mysecret,src=.mysecret .
+$ podman build --secret=id=mysecret,src=.mysecret,type=file .
+```
+
 ### Building a multi-architecture image using the --manifest option (requires emulation software)
 
 Build image using the specified architectures and link to a single manifest on successful completion: