(PDOC-128) Add explanation of @example tag usage in README

README.md

@@ -328,6 +328,29 @@ function example(String $name) {
 ***Note: Puppet Strings will automatically use the parameter type information from the function's parameter list to document
 the parameter types.***
 
+Further examples
+----------------
+
+#### Using The `@example` Tag
+
+The `@example` YARD tag can be used to add usage examples to any Ruby or Puppet language code.
+
+```puppet
+# @example String describing what this example demonstrates.
+#   $content = example('world')
+#   if $content == 'world' {
+#     include world
+#   }
+function example(string $name) {
+  "hello $name"
+}
+```
+
+The string following the `@example` tag is an optional title which is displayed prominently above the code block.
+
+The example body must begin on a newline underneath the tag, and each line of the example itself must be indented by
+at least one space. Further indentation is preserved as preformatted text in the generated documentation.
+
 Additional Resources
 --------------------