Ruff! (v2.4.2)

::ruff::sampleTop, Main, Index

IntroductionTop, Main, Index

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.

FormattingTop, Main, Index

The formatting elements described below may appear both within _ruff_preamble content as well as proc and method comments.

ListsTop, Main, Index

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.

itemaDefinition of item A.
itembDefinition of item B across multiple lines.

Inline formattingTop, Main, Index

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.

LinksTop, Main, Index

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.

Fenced blocksTop, Main, Index

``` -caption "A fenced block"
Lines consisting of *3* or more backquotes can be used
to bracket unformatted content
like
this paragraph.
```
Lines consisting of *3* or more backquotes can be used
to bracket unformatted content
like
this paragraph.
Figure 3. A fenced block

The -caption option is optional. If specified, it is shown below the output and can be linked to using the value of the option. For example [A fenced block] will link as Figure 3. A fenced block.

In the HTML formatter, captions are automatically prefixed as Figure 1, Figure 2 etc.. The numbering is across the entire document set, not per page, by design.

The fence can be followed by a language specifier (any string) *without any intervening whitespace.

```tcl
set lang "This is Tcl code"
```
set lang "This is Tcl code"

Not all formatters make use of the language specifier.

DiagramsTop, Main, Index

Diagrams can be embedded in several formats such as ditaa,

``` -caption "A ditaa diagram" diagram ditaa
+--------+   +-------+    +-------+
|        | --+ ditaa +--> |       |
|  Text  |   +-------+    |diagram|
|Document|   |!magic!|    |       |
|     {d}|   |       |    |       |
+---+----+   +-------+    +-------+
:                         ^
|       Lots of work      |
+-------------------------+
```
Figure 4. A ditaa diagram

or PlantUML,

``` -caption "A PlantUML diagram generated by kroki" diagram kroki plantuml
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml
```
Figure 5. A PlantUML diagram generated by kroki

and several others. You can link to a diagram using the string specified with its -caption option.

ImagesTop, Main, Index

Images can be specified using either Markdown or HTML:

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.

CommandsTop, Main, Index

character_at [::ruff::sample]Top, Main, Index

Get the character from a string.

character_at text ?pos?
Details
Parameters
textText string.
posCharacter position. Optional, default 0.
Description

The command will treat negative values of $pos as offset from the end of the string.

Note the use of Returns: as opposed to Returns (i.e. with a colon) in the source comments. See docs for the difference.

An error exception is raised if $pos is not within bounds.

Return value

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.
    #
    # Note the use of `Returns:` as opposed to `Returns` (i.e. with a colon) in
    # the source comments. See docs for the difference.
    #
    # 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]
    }
}

ensemble_proc [::ruff::sample]Top, Main, Index

A command ensemble.

ensemble_proc subcommand ...
Details
Description

The ensemble supports the following subcommands:

cmdAImplements cmdA for an ensemble procedure.
cmdBImplements cmdB for an ensemble procedure.

Refer to the documentation of each subcommand for details.

ensemble_proc cmdA [::ruff::sample]Top, Main, Index

Implements cmdA for an ensemble procedure

ensemble_proc cmdA
Details
proc ::ruff::sample::ensemble_proc::cmdA {} {

    # Implements cmdA for an ensemble procedure
}
# NOTE: showing source of procedure implementing ensemble subcommand.

ensemble_proc cmdB [::ruff::sample]Top, Main, Index

Implements cmdB for an ensemble procedure

ensemble_proc cmdB paramA paramB
ensemble_proc cmdB paramX
Details
Parameters
paramAThe first param.
paramBThe optional second param.
proc ::ruff::sample::ensemble_proc::cmdB {args} {

    # Implements cmdB for an ensemble procedure
    #  paramA - the first param
    #  paramB - the optional second param
    # Synopsis: paramA paramB
    # Synopsis: paramX
}
# NOTE: showing source of procedure implementing ensemble subcommand.

proc_full [::ruff::sample]Top, Main, Index

This first line is the summary line for documentation.

proc_full arg ?optarg? ?args?
Details
Parameters
argFirst parameter.
optargAn optional parameter. Optional, default AVALUE.
-switch VALUEAn optional switch.
Description

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:

AVALUEOne possible value.
BVALUEAnother possible value.
CVALUEA 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. Each line of this section must be parsable as a Tcl list.

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.

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.

See also

proc_without_docs, Base, https://www.magicsplat.com, ensemble_proc cmdA, ensemble_proc cmdB, proc_full, character_at

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. Each line of this section
    # must be parsable as a Tcl list.
    #
    # See also: proc_without_docs [Base] <https://www.magicsplat.com>
    #   "ensemble_proc cmdA" {ensemble_proc cmdB}
    # See also: proc_full
    # See also: character_at


    # 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.
}

proc_with_custom_synopsis [::ruff::sample]Top, Main, Index

This is a proc with a custom synopsis

proc_with_custom_synopsis A B C D
proc_with_custom_synopsis DIFFERENT_PARAM_SIG
proc_with_custom_synopsis X Y args
Details
Parameters
AArg A for first synopsis.
BArg V for first synopsis.
DIFFERENT_PARAM_SIGArg for another synopsis.
Description

A custom synopsis is useful when a command takes several different argument structures.

proc ::ruff::sample::proc_with_custom_synopsis {args} {

    # This is a proc with a custom synopsis
    #  A - arg A for first synopsis
    #  B - arg V for first synopsis
    #  DIFFERENT_PARAM_SIG - arg for another synopsis
    # A custom synopsis is useful when a command takes several
    # different argument structures.
    # Synopsis: A B
    #   C D
    # Synopsis: DIFFERENT_PARAM_SIG
    # Synopsis: X Y args
}

proc_without_docs [::ruff::sample]Top, Main, Index

proc_without_docs first_arg second_arg
Details
Parameters
first_argNot documented.
second_argNot documented.
proc ::ruff::sample::proc_without_docs {first_arg second_arg} {

}

ClassesTop, Main, Index

Base [::ruff::sample]Top, Main, Index

Method summary
constructorConstructor for the class.
destructorDestructor for the class.
<tag>An explicitly exported method looking like a html tag.
base_methodBase_method is defined only in the base class.
fwd_methodMethod forwarded to string range.
overridable_methodThis method will be overridden in the derived class.
propertyMethod with custom synopsis.
Subclasses

Derived

constructor [::ruff::sample::Base]Base, Top, Main, Index

Constructs the class

Base create OBJNAME arg
Base new arg
Details
Parameters
argArgument to constructor.
Description

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.
}

destructor [::ruff::sample::Base]Base, Top, Main, Index

Releases all resources and destroys the class

OBJECT destroy
Details
method destructor {} {

    # Releases all resources and destroys the class
}

<tag> [::ruff::sample::Base]Base, Top, Main, Index

An explicitly exported method looking like a html tag

OBJECT <tag>
Details
Description

Verify it also shows in base_method description as well as See also section.

method <tag> {} {

    # An explicitly exported method looking like a html tag
    #
    # Verify it also shows in [base_method] description as well
    # as See also section.
}

base_method [::ruff::sample::Base]Base, Top, Main, Index

base_method is defined only in the base class

OBJECT base_method arga argb
Details
Parameters
argaFirst argument.
argbSecond argument from.
Description

This is method m1

This is a reference to method <tag>.

See also

<tag>

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 is a reference to method [<tag>].
    #
    # See also: <tag>
}

fwd_method [::ruff::sample::Base]Base, Top, Main, Index

Forwarded to string range.

overridable_method [::ruff::sample::Base]Base, Top, Main, Index

This method will be overridden in the derived class

OBJECT overridable_method
Details
Description

Calls base_method

method overridable_method {} {

    # This method will be overridden in the derived class
    #
    # Calls [base_method]
}

property [::ruff::sample::Base]Base, Top, Main, Index

Method with custom synopsis

OBJECT property PROPERTYNAME
OBJECT property PROPERTYNAME ?VALUE?
Details
Parameters
PROPERTYNAMEName of property.
VALUEValue to set for property.
method property {args} {

    # Method with custom synopsis
    #  PROPERTYNAME - name of property
    #  VALUE - value to set for property
    # Synopsis: PROPERTYNAME
    # Synopsis: PROPERTYNAME ?VALUE?
}

ConfigurableClass [::ruff::sample]Top, Main, Index

Method summary
constructorConstructor for the class.
configureConfigure properties.
Properties

Readable: -rprop, -rwprop

Writable: -rwprop, -wprop

constructor [::ruff::sample::ConfigurableClass]ConfigurableClass, Top, Main, Index

A class with properties

ConfigurableClass create OBJNAME
ConfigurableClass new
Details
method constructor {} {

    # A class with properties
}

Derived [::ruff::sample]Top, Main, Index

Method summary
<tag>See Base.<tag>
added_methodMethod defined only in Derived.
base_methodSee Base.base_method
fwd_methodSee Base.fwd_method
mixed_in_methodSee Mixin.mixed_in_method
overridable_methodThis method overrides the one defined in Base.
propertySee Base.property
Superclasses

Base

Mixins

Mixin

added_method [::ruff::sample::Derived]Derived, Top, Main, Index

Method defined only in Derived.

OBJECT added_method
Details
method added_method {} {

    # Method defined only in [Derived].
}

overridable_method [::ruff::sample::Derived]Derived, Top, Main, Index

This method overrides the one defined in Base.

OBJECT overridable_method
Details
method overridable_method {} {

    # This method overrides the one defined in [Base].
}

FunnyMethods [::ruff::sample]Top, Main, Index

Method summary
constructorConstructor for the class.
&Method to test & escaping in HTML.
*Method to test regexp special chars.
+Method to test regexp special chars.
<Method to test < escaping in HTML.
>Method to test > escaping in HTML.
_Method to test underscores.

constructor [::ruff::sample::FunnyMethods]FunnyMethods, Top, Main, Index

Class for testing special characters in method names

FunnyMethods create OBJNAME
FunnyMethods new
Details
method constructor {} {

    # Class for testing special characters in method names
}

& [::ruff::sample::FunnyMethods]FunnyMethods, Top, Main, Index

Method to test & escaping in HTML

OBJECT &
Details
method & {} {

    # Method to test & escaping in HTML
}

* [::ruff::sample::FunnyMethods]FunnyMethods, Top, Main, Index

Method to test regexp special chars

OBJECT *
Details
method * {} {

    # Method to test regexp special chars
}

+ [::ruff::sample::FunnyMethods]FunnyMethods, Top, Main, Index

Method to test regexp special chars

OBJECT +
Details
method + {} {

    # Method to test regexp special chars
}

< [::ruff::sample::FunnyMethods]FunnyMethods, Top, Main, Index

Method to test < escaping in HTML

OBJECT <
Details
method < {} {

    # Method to test < escaping in HTML
}

> [::ruff::sample::FunnyMethods]FunnyMethods, Top, Main, Index

Method to test > escaping in HTML

OBJECT >
Details
method > {} {

    # Method to test > escaping in HTML
}

_ [::ruff::sample::FunnyMethods]FunnyMethods, Top, Main, Index

Method to test underscores

OBJECT _
Details
method _ {} {

    # Method to test underscores
}

MetaClass [::ruff::sample]Top, Main, Index

Method summary
createSee [::oo::class.create]
newSee [::oo::class.new]
Superclasses

[::oo::class]

MetaClassInstance [::ruff::sample]Top, Main, Index

Method summary
amethodA method of a class created from a metaclass.

amethod [::ruff::sample::MetaClassInstance]MetaClassInstance, Top, Main, Index

A method of a class created from a metaclass

OBJECT amethod
Details
method amethod {} {

    # A method of a class created from a metaclass
}

Mixin [::ruff::sample]Top, Main, Index

Method summary
mixed_in_methodThis method will be mixed into a class.
Subclasses

Derived

mixed_in_method [::ruff::sample::Mixin]Mixin, Top, Main, Index

This method will be mixed into a class.

OBJECT mixed_in_method arg
Details
Parameters
argAn argument to the method.
method mixed_in_method {arg} {

    # This method will be mixed into a class.
    # arg - an argument to the method
}