From dae114a7f3fb5cab07ad793eeb43dc57ac5b7c64 Mon Sep 17 00:00:00 2001
From: Luke Imhoff <luke_imhoff@rapid7.com>
Date: Mon, 27 Oct 2014 15:59:12 -0500
Subject: [PATCH] Document how to derive reference_name from ancestors

MSP-11145
---
 .../examples/payload_can_be_instantiated.rb   | 31 ++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/spec/support/shared/examples/payload_can_be_instantiated.rb b/spec/support/shared/examples/payload_can_be_instantiated.rb
index 561dbe3e1e..a27323aaa7 100644
--- a/spec/support/shared/examples/payload_can_be_instantiated.rb
+++ b/spec/support/shared/examples/payload_can_be_instantiated.rb
@@ -3,6 +3,31 @@
 # Tests that the `:ancestor_reference_names` can be loaded from `:modules_pathname` and once the ancestors are loaded
 # that `:reference_name` can be instantiated.
 #
+# # Payload Reference Name Derivation
+# You can see this naming logic [here](https://github.com/rapid7/metasploit-framework/blob/1508be6254f698f345616d14415bce164bf377f9/lib/msf/core/payload_set.rb#L132-L148).
+#
+# ## Single
+# 1. Remove the payload type prefix, `modules/payloads/singles`, from the path.
+# 2. Remove the file extension, `.rb` from the path
+#
+# This is <reference_name>
+#
+# ## Staged
+#
+# ### Stager
+# Determine if the stager module has a `handler_type_alias`
+# No) Use stager's handler's `handler_type` as `<handler_type>`.
+# Yes) Use the return value from `handler_type_alias` as `<handler_type>`.
+#
+# ### Stage
+# 1. Remove the payload type prefix, `modules/payloads/stages`, from the path.
+# 2. Remove the file extension, `.rb` from the path.
+#
+# This is <stage_reference_name>.
+#
+# ### Combining
+# The final staged module's combined `<reference_name>` is `<stage_reference_name>/<handler_type>`.
+#
 # @example Using 'payload can be instantiated' with `Metasploit::Framework::Spec::UntestedPayloads.define_task` and 'untested payloads' shared context
 #   # Rakefile
 #   require 'metasploit/framework/spec/untested_payloads'
@@ -33,7 +58,11 @@
 #
 # @param options [Hash{Symbol => Array<String>, Pathname, String}]
 # @option options [Array<String>] :ancestor_reference_names The reference names of the payload modules that are included
-#   in {Msf::Payload} to make the `:reference_name` payload.
+#   in {Msf::Payload} to make the `:reference_name` payload.  Ancestor reference names are the names of the files under
+#   `modules/payloads` without the extension `.rb` that are mixed together to form a payload module `Class`.  For
+#   single payloads, there will be one ancestor reference name from `modules/payloads/singles`, while for staged
+#   payloads there with be one ancestor reference name from `modules/payloads/stagers` and one ancestor reference name
+#   from `modules/payloads/stages`.
 # @option options [Pathname] :modules_pathname The `modules` directory from which to load `:ancestor_reference_names`.
 # @option options [String] :reference_name The reference name for payload class that should be instantiated from mixing
 #   `:ancestor_reference_names`.