diff --git a/makefiles/virtualenv/include.mk b/makefiles/virtualenv/include.mk
index c20333f..2ce04d2 100644
--- a/makefiles/virtualenv/include.mk
+++ b/makefiles/virtualenv/include.mk
@@ -14,15 +14,30 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # -----------------------------------------------------------------------
-# https://gerrit.opencord.org/plugins/gitiles/onf-make
-# ONF.makefile.virtualenv.version = 1.2
+# -----------------------------------------------------------------------
+# Intent:
+#   This makefile defines dependencies that will install a python virtualenv
+#   beneath $(sandbox)/.venv/.  The $(activate) macro is used to source
+#   .venv/bin/activate allowing command python and pip to be used.
 # -----------------------------------------------------------------------
 # Usage:
-#   include makefiles/virtualenv/include.m
+#   include makefiles/virtualenv/include.mk
 #
-#   Target Dependencies:
-#     tgt : $(venv-activate-patched)     python 3.10+ local use
-#     tgt : $(venv-activate-script)      python < v3.8
+# Makefile Target Dependencies:
+#     tgt : $(venv-activate-patched)      # python 3.10+ local use
+#     tgt : $(venv-activate-script)       # python < v3.8
+#
+# Make definitions (convenience macros used for command access)
+#   PIP    := $(activate) && pip          # invoke pip from virtualenv
+#   PYTHON := $(activate) && python       # invoke python from virtualenv
+#
+# Target declaration and command invocation:
+#   my-target : $(venv-activate-script)   # dependency installs virtualenv
+#   <tab>$(PYTHON) --version              # invoke python with arguments
+#	<tab>$(PYTHON) my-command.py
+#	<tab>$(activate) && pip install foobar
+#
+#   % make my-target                      # Invoke make target from shell
 # -----------------------------------------------------------------------
 
 $(if $(DEBUG),$(warning ENTER))
@@ -40,8 +55,12 @@
 venv-activate-bin    := $(venv-name)/bin#                 # no whitespace
 venv-activate-script := $(venv-activate-bin)/activate#    # dependency
 
-# Intent: activate= is a macro for accessing the virtualenv activation script#
-#  Usage: $(activate) && python
+# ------------------------------------------------------------------------
+# Intent: Define macro activate= to access virtualenv activation script.
+#  Usage:
+#    - $(activate) && python             # Syntax inlined within a target
+#    - PYTHON := $(activate) && python   # Define a named command macro
+# ------------------------------------------------------------------------
 activate             ?= set +u && source $(venv-activate-script) && set -u
 
 ## -----------------------------------------------------------------------