::ruff::sampleMain

Introductionsample, Main

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.

Formattingsample, Main

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

Listssample, Main

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.

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

Inline formattingsample, Main

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.

Linkssample, Main

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.

Preformatted blockssample, Main

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

Commandssample, Main

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

Get the character from a string.

character_at text ?pos?
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.

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

Return value

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

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

Implements cmdA for an ensemble procedure

ensemble_proc cmdA
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]sample, Main

Implements cmdB for an ensemble procedure

ensemble_proc cmdB
proc ::ruff::sample::ensemble_proc::cmdB {} {

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

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

This first line is the summary line for documentation.

proc_full arg ?optarg? ?args?
Parameters
argFirst parameter.
optargAn optional parameter. Optional, default AVALUE.
argsOptional arguments.
-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.

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

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

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

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

}

Classessample, Main

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

Method summary
constructorConstructor for the class.
destructorDestructor for the class.
<tag>An explicitly exported method.
base_methodBase_method is defined only in the base class.
overridable_methodThis method will be overridden in the derived class.
Subclasses

Derived

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

Constructs the class

Base create arg
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, Main

Releases all resources and destroys the class

OBJECT destroy
method destructor {} {

    # Releases all resources and destroys the class
}

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

An explicitly exported method

OBJECT <tag>
method <tag> {} {

    # An explicitly exported method
}

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

base_method is defined only in the base class

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

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
}

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

This method will be overridden in the derived class

OBJECT overridable_method
Description

Calls base_method

method overridable_method {} {

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

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

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

Base

Mixins

Mixin

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

Method defined only in Derived.

OBJECT added_method
method added_method {} {

    # Method defined only in [Derived].
}

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

This method overrides the one defined in Base.

OBJECT overridable_method
method overridable_method {} {

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

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

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

Derived

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

This method will be mixed into a class.

OBJECT mixed_in_method arg
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
}
Document generated by Ruff!
© 2019 Ashok P. Nadkarni