shared/fn-ref-ex.asciidoc

////
Below is a sample function reference listing.
A heading and short description are visible.
Other content is hidden in a collapsible block.
////

[[sample-fn]]
=== `substring`

////
A brief 1-2 sentence description.
////
Does a cool thing.

[%collapsible]
====

////
An example using the function.
The goal is to show an input and output.
If needed, you can include the return output in a comment.
////

*Example*
[source,txt]
----
substring("quick brown fox", 0, 5)      // returns "quick"
substring("quick brown fox", 6, 11)     // returns "brown"
substring("quick brown fox", 6)         // returns "b"
substring("quick brown fox", -3, -1)    // returns "fo"
substring("quick brown fox", -3)        // returns "f"
----

////
A snippet outlining the function syntax.
Unnamed parameters are included using angle brackets (e.g. `<parm>`).
Optional parameters are included using square brackets (e.g. [<parm>]).
////

*Syntax*
[source,txt]
----
substring(<source>, <start_pos>[, <end_pos>])
----

////
Guidelines for parameter documentation
***************************************
* Use a definition list.
* End each definition with a period.
* Include whether the parameter is Optional or Required and the data type.
* For parameters that accept multiple arguments, add `{multi-arg}` to the first
  occurrence. Use `{multi-arg-ref}` in subsequent occurrences.
* Include default values as the last sentence of the first paragraph.
* Include a range of valid values, if applicable.
* If the parameter requires a specific delimiter for multiple values, say so.
* If the parameter supports wildcards, ditto.
***************************************
////

*Parameters*
`<source>`::
(Required, string)
Source string used for extraction.

`<start_pos>`::
(Required, integer)
Starting position for extraction.
+
Positions are zero-indexed. Negative offsets are supported.

`<end_pos>`::
(Optional{multi-arg}, integer)
End position for extraction. If this position is not provided, the function only
extracts the character in the `<start_pos>` position.
+
Positions are zero-indexed. Negative offsets are supported.

////
Data type returned by the function.
////

*Returns:* string
====