The code in this namespace illustrates the various documentation features in Ruff!. The corresponding source is here or click the Show source link below each procedure or method documentation to see the source from which the documentation was generated. See the main ::ruff documentation for a full description.
The documentation (such as this section) not specific to a procedure or method is placed in the variable _ruff_preamble
within each namespace.
The formatting elements described below may appear both within _ruff_preamble
content as well as proc and method comments.
This is an unnumbered list.
* First item * Second item across multiple lines * Third item
This is displayed as
This is a definition list.
itema - Definition of item A itemb - Definition of item B across multiple lines.
Definition lists are displayed in an output-specific format.
itema | Definition of item A. |
itemb | Definition of item B across multiple lines. |
Basic markdown inline formatting is supported as `code`, *emphasis*, **strong** and ***strong emphasis***.
Basic markdown inline formatting is supported as code
, emphasis, strong and strong emphasis.
Links may be references to program elements, e.g. [Derived], to external resources, e.g. [example](https://www.example.com) or explicit, e.g. <https://ruff.magicsplat.com>.
Links may be references to program elements, e.g. Derived, to external resources, e.g. example or explicit, e.g. https://ruff.magicsplat.com.
``` Lines consisting of *3* or more backquotes can be used to bracket unformatted content like this paragraph. ```
The remaining sections show how commands and classes are documented. Click on the Show source link to see the underlying source code for the procedure or method from which the documentation was generated.
Get the character from a string.
text | Text string. |
pos | Character position. Optional, default 0 . |
The command will treat negative values of $pos
as offset from the end of the string.
An error exception is raised if $pos
is not within bounds.
Returns the character at index $pos
in string $text
.
proc ::ruff::sample::character_at {text {pos 0}} { # Get the character from a string. # text - Text string. # pos - Character position. # The command will treat negative values of $pos as offset from # the end of the string. # # Returns the character at index $pos in string $text. set n [string length $text] if {[tcl::mathfunc::abs $pos] >= [string length $text]} { #ruff # An error exception is raised if $pos is not within bounds. error "Index $pos out of bounds." } if {$pos < 0} { return [string index $text end$pos] } else { return [string index $text $pos] } }
Implements cmdA for an ensemble procedure
proc ::ruff::sample::ensemble_proc::cmdA {} { # Implements cmdA for an ensemble procedure } # NOTE: showing source of procedure implementing ensemble subcommand.
Implements cmdB for an ensemble procedure
proc ::ruff::sample::ensemble_proc::cmdB {} { # Implements cmdB for an ensemble procedure } # NOTE: showing source of procedure implementing ensemble subcommand.
This first line is the summary line for documentation.
arg | First parameter. |
optarg | An optional parameter. Optional, default AVALUE . |
args | Optional arguments. |
-switch VALUE | An optional switch. |
This is the general description of the procedure composed of multiple paragraphs. It is separated from the parameter list above by one or more empty comments.
This is the second paragraph. The next paragraph (in the source comments) starts with the word Returns and hence will be treated by Ruff! as describing the return value.
A definition list has a similar form to the argument list. For example, optarg may take the following values:
AVALUE | One possible value. |
BVALUE | Another possible value. |
CVALUE | A third value but note the intervening blank comment above in the source code. |
Bullet lists are indicated by a starting -
or *
character.
An optional See also section may be used to cross-reference other program elements.
Thanks to the #ruff marker, this paragraph will be included by Ruff! even though it is not in the initial block of comments. This is useful for putting documentation for a feature right next to the code implementing it.
Returns a value. Because it started with the Returns keyword, this paragraph is treated as the return value description no matter where it appears.
proc ::ruff::sample::proc_full {arg {optarg AVALUE} args} { # This first line is the summary line for documentation. # arg - first parameter # optarg - an optional parameter # -switch VALUE - an optional switch # # This is the general description of the procedure # composed of multiple paragraphs. It is separated from # the parameter list above by one or more empty comments. # # This is the second paragraph. The next paragraph (in the *source* comments) # starts with the word Returns and hence will be treated # by Ruff! as describing the return value. # # Returns a value. Because it started with the **Returns** # keyword, this paragraph is treated as the return value # description no matter where it appears. # # A definition list has a similar form to the argument # list. For example, optarg may take the following values: # AVALUE - one possible value # BVALUE - another possible value # # CVALUE - a third value but note the intervening blank comment # above in the source code. # Bullet lists are indicated by a starting `-` or `*` character. # - This is a bullet list iterm # * This is also a bullet list item # # An optional *See also* section may be used to # cross-reference other program elements. # See also: proc_without_docs [Base] # This paragraph will be ignored by Ruff! as it is not part # of the initial block of comments. some code #ruff # Thanks to the #ruff marker, this paragraph will be # included by Ruff! even though it is not in the initial block # of comments. This is useful for putting documentation for # a feature right next to the code implementing it. some more code. }
first_arg | Not documented. |
second_arg | Not documented. |
proc ::ruff::sample::proc_without_docs {first_arg second_arg} { }
constructor | Constructor for the class. |
destructor | Destructor for the class. |
<tag> | An explicitly exported method. |
base_method | Base_method is defined only in the base class. |
overridable_method | This method will be overridden in the derived class. |
Constructs the class
arg | Argument to constructor. |
The constructor for the class should also include general information for the class.
method constructor {arg} { # Constructs the class # arg - argument to constructor # The constructor for the class should also include # general information for the class. }
Releases all resources and destroys the class
method destructor {} { # Releases all resources and destroys the class }
An explicitly exported method
method <tag> {} { # An explicitly exported method }
base_method is defined only in the base class
arga | First argument. |
argb | Second argument from. |
This is method m1
method base_method {arga argb} { # base_method is defined only in the base class # arga - first argument # argb - second argument from # # This is method m1 }
This method will be overridden in the derived class
Calls base_method
method overridable_method {} { # This method will be overridden in the derived class # # Calls [base_method] }
<tag> | See Base.<tag> |
added_method | Method defined only in Derived. |
base_method | See Base.base_method |
mixed_in_method | See Mixin.mixed_in_method |
overridable_method | This method overrides the one defined in Base. |
Method defined only in Derived.
method added_method {} { # Method defined only in [Derived]. }
This method overrides the one defined in Base.
method overridable_method {} { # This method overrides the one defined in [Base]. }
mixed_in_method | This method will be mixed into a class. |
This method will be mixed into a class.
arg | An argument to the method. |
method mixed_in_method {arg} { # This method will be mixed into a class. # arg - an argument to the method }