ExamplesTop, Main, Index

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

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

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

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 ::ruff::sample::proc_args_and_options {c a b args} {

    # This proc for testing argument order
    #
    # -secondopt - second option
    # b - arg b
    # a - arg a
    # c - arg c
    # args - optional args
    # -firstopt - first option
}

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 ::ruff::sample::proc_with_conditional_content {} {

    # This is a proc that uses `#ruffopt` directive to select content based formatter.
    #
    #ruffopt includedformats html
    # <div style="ruff_bd"> <table class="ruff_deflist"> <tbody>
    # <tr><th>Column1</th><th>Column2</th><th>Column3</th><th>Column4</th><th>Column5</th></tr>
    # <tr><td>1</td><td>element1</td><td>element2</td><td>element3</td><td>element4</td></tr>
    # <tr><td>2</td><td>element5</td><td>element6</td><td>element7</td><td>element8</td></tr>
    # </tbody> </table> </div>
    #
    #ruffopt excludedformats {html markdown}
    #```
    # ┌─────────┬──────────┬──────────┬──────────┬──────────┐
    # │ Column1 │ Column2  │ Column3  │ Column4  │ Column5  │
    # ├─────────┼──────────┼──────────┼──────────┼──────────┤
    # │ 1       │ element1 │ element2 │ element3 │ element4 │
    # │ 2       │ element5 │ element6 │ element7 │ element8 │
    # └─────────┴──────────┴──────────┴──────────┴──────────┘
    #```
    #
    #ruffopt includedformats markdown
    #| Column1 | Column2  | Column3  | Column4  | Column5  |
    #|---------|----------|----------|----------|----------|
    #| 1       | element1 | element2 | element3 | element4 |
    #| 2       | element5 | element6 | element7 | element8 |
}

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 ::ruff::sample::proc_without_docs {first_arg second_arg} {

}

method constructor {arg} {

    # Constructs the class
    #   arg - argument to constructor
    # The constructor for the class should also include
    # general information for the class.
}

method destructor {} {

    # Releases all resources and destroys the class
}

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

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

method class_method {} {

    # This method is defined on the class, not class instance
}

method overridable_method {} {

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

method property {args} {

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

method m {a b} {

}

method constructor {} {

    # A class with properties
}

method added_method {} {

    # Method defined only in [Derived].
}

method overridable_method {} {

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

method constructor {} {

    # Class for testing special characters in method names
}

method & {} {

    # Method to test & escaping in HTML
}

method * {} {

    # Method to test regexp special chars
}

method + {} {

    # Method to test regexp special chars
}

method < {} {

    # Method to test < escaping in HTML
}

method > {} {

    # Method to test > escaping in HTML
}

method _ {} {

    # Method to test underscores
}

method ` {} {

    # Method to test ` (backquote)
}

method trailing` {} {

    # Method to test trailing` (backquote)
}

method amethod {} {

    # A method of a class created from a metaclass
}

method mixed_in_method {arg} {

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