Ruff!

# ::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

- First item
- Second item across multiple lines
- Third item

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.

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

### 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:

- `![alt img](assets/ruff-logo.png)`
- `<img src='assets/ruff-logo.png' alt='logo'/>`
- `<img src="assets/ruff-logo.png" alt=""/>`

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?

##### Parameters

`text` | Text string.
`pos` | Character 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`.

Show source

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

##### Description

The ensemble supports the following subcommands:

cmdA | Implements cmdA for an ensemble procedure.
cmdB | Implements 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

Show source

    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

##### Parameters

`paramA` | The first param.
`paramB` | The optional second param.

Show source

    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?

##### Parameters

`arg` | First parameter.
`optarg` | An optional parameter. Optional, default `AVALUE`.
`-switch VALUE` | An 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:

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.

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

Show source

    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

##### Parameters

`A` | Arg A for first synopsis.
`B` | Arg V for first synopsis.
`DIFFERENT_PARAM_SIG` | Arg for another synopsis.

##### Description

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

Show source

    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

##### Parameters

`first_arg` | Not documented.
`second_arg` | Not documented.

Show source

    proc ::ruff::sample::proc_without_docs {first_arg second_arg} {

    }

## ClassesTop, Main, Index

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

##### Method summary

constructor | Constructor for the class.
destructor | Destructor for the class.
<tag> | An explicitly exported method looking like a html tag.
base_method | Base_method is defined only in the base class.
fwd_method | Method forwarded to string range.
overridable_method | This method will be overridden in the derived class.
property | Method with custom synopsis.

##### Subclasses

Derived

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

Constructs the class

Base create OBJNAME arg
Base new arg

##### Parameters

`arg` | Argument to constructor.

##### Description

The constructor for the class should also include general information for the class.

Show source

    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

Show source

    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>

##### Description

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

Show source

    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

##### Parameters

`arga` | First argument.
`argb` | Second argument from.

##### Description

This is method m1

This is a reference to method <tag>.

##### See also

<tag>

Show source

    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

##### Description

Calls base_method

Show source

    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?

##### Parameters

`PROPERTYNAME` | Name of property.
`VALUE` | Value to set for property.

Show source

    method property {args} {

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

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

##### Method summary

`<tag>` | See Base.<tag>
added_method | Method defined only in Derived.
`base_method` | See Base.base_method
`fwd_method` | See Base.fwd_method
`mixed_in_method` | See Mixin.mixed_in_method
overridable_method | This method overrides the one defined in Base.
`property` | See Base.property

##### Superclasses

Base

##### Mixins

Mixin

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

Method defined only in Derived.

OBJECT added_method

Show source

    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

Show source

    method overridable_method {} {

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

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

##### Method summary

constructor | Constructor 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

Show source

    method constructor {} {

        # Class for testing special characters in method names
    }

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

Method to test & escaping in HTML

OBJECT &

Show source

    method & {} {

        # Method to test & escaping in HTML
    }

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

Method to test regexp special chars

OBJECT *

Show source

    method * {} {

        # Method to test regexp special chars
    }

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

Method to test regexp special chars

OBJECT +

Show source

    method + {} {

        # Method to test regexp special chars
    }

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

Method to test < escaping in HTML

OBJECT <

Show source

    method < {} {

        # Method to test < escaping in HTML
    }

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

Method to test > escaping in HTML

OBJECT >

Show source

    method > {} {

        # Method to test > escaping in HTML
    }

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

Method to test underscores

OBJECT _

Show source

    method _ {} {

        # Method to test underscores
    }

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

##### Method summary

`create` | See [::oo::class.create]
`new` | See [::oo::class.new]

##### Superclasses

[::oo::class]

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

##### Method summary

amethod | A 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

Show source

    method amethod {} {

        # A method of a class created from a metaclass
    }

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

##### Method summary

mixed_in_method | This 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

##### Parameters

`arg` | An argument to the method.

Show source

    method mixed_in_method {arg} {

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