Documenting code

Documentation for API features can be written in code comments directly preceding the definition of the respective feature.

By default, all public methods, macros, types and constants are considered part of the API documentation.

tip The compiler command crystal docs automatically extracts the API documentation and generates a website to present it.

Association

Doc comments must be positioned directly above the definition of the documented feature. Consecutive comment lines are combined into a single comment block. Any empty line breaks the association to the documented feature.

  1. # This comment is not associated with the class.
  2. # First line of documentation for class Unicorn.
  3. # Second line of documentation for class Unicorn.
  4. class Unicorn
  5. end

Format

Doc comments support Markdown formatting.

The first paragraph of a doc comment is considered its summary. It should concisely define the purpose and functionality.

Supplementary details and usages instructions should follow in subsequent paragraphs.

For instance:

  1. # Returns the number of horns this unicorn has.
  2. #
  3. # Always returns `1`.
  4. def horns
  5. 1
  6. end

tip It is generally advised to use descriptive, third person present tense: Returns the number of horns this unicorn has (instead of an imperative Return the number of horns this unicorn has).

Markup

Linking

References to other API features can be enclosed in single backticks. They are automatically resolved and converted into links to the respective feature.

  1. class Unicorn
  2. # Creates a new `Unicorn` instance.
  3. def initialize
  4. end
  5. end

The same lookup rules apply as in Crystal code. Features in the currently documented namespace can be accessed with relative names:

  • Instance methods are referenced with a hash prefix: #horns.
  • Class methods are referenced with a dot prefix: .new.
  • Constants and types are referenced by their name: Unicorn.

Features in other namespaces are referenced with the fully-qualified type path: Unicorn#horns, Unicorn.new, Unicorn::CONST.

Different overloads of a method can be identified by the full signature .new(name), .new(name, age).

Parameters

When refering to parameters, it is recommended to write their name italicized (*italicized*):

  1. # Creates a unicorn with the specified number of *horns*.
  2. def initialize(@horns = 1)
  3. raise "Not a unicorn" if @horns != 1
  4. end

Code Examples

Code examples can be placed in Markdown code blocks. If no language tag is given, the code block is considered to be Crystal code.

  1. # Example:
  2. #

unicorn = Unicorn.new

unicorn.horns # => 1

```

class Unicorn end

  1. To designate a code block as plain text, it must be explicitly tagged.
  2. ```crystal
  3. # Output:
  4. # ```plain
  5. # "I'm a unicorn"
  6. #

def say puts “I’m a unicorn” end

  1. Other language tags can also be used.
  2. To show the value of an expression inside code blocks, use `# =>`.
  3. ```crystal
  4. 1 + 2 # => 3
  5. Unicorn.new.speak # => "I'm a unicorn"

Admonitions

Several admonition keywords are supported to visually highlight problems, notes and/or possible issues.

  • BUG
  • DEPRECATED
  • EXPERIMENTAL
  • FIXME
  • NOTE
  • OPTIMIZE
  • TODO
  • WARNING

Admonition keywords must be the first word in their respective line and must be in all caps. An optional trailing colon is preferred for readability.

  1. # Makes the unicorn speak to STDOUT
  2. #
  3. # NOTE: Although unicorns don't normally talk, this one is special
  4. # TODO: Check if unicorn is asleep and raise exception if not able to speak
  5. # TODO: Create another `speak` method that takes and prints a string
  6. def speak
  7. puts "I'm a unicorn"
  8. end
  9. # Makes the unicorn talk to STDOUT
  10. #
  11. # DEPRECATED: Use `speak`
  12. def talk
  13. puts "I'm a unicorn"
  14. end

The compiler implicitly adds some admonitions to doc comments:

Directives

Directives tell the documentation generator how to treat documentation for a specific feature.

ditto

If two consecutively defined features have the same documentation, :ditto: can be used to copy the same doc comment from the previous definition.

  1. # Returns the number of horns.
  2. def horns
  3. horns
  4. end
  5. # :ditto:
  6. def number_of_horns
  7. horns
  8. end

The directive needs to be on a separate line but further documentation can be added in other lines. The :ditto: directive is simply replaced by the content of the previous doc comment.

nodoc

Public features can be hidden from the API docs with the :nodoc: directive. Private and protected features are always hidden.

  1. # :nodoc:
  2. class InternalHelper
  3. end

This directive needs to be the first line in a doc comment. Leading whitespace if optional. Following comment lines can be used for internal documentation.

inherit

See Inheriting Documentation.

Inheriting Documentation

When an instance method has no doc comment, but a method with the same signature exists in a parent type, the documentation is inherited from the parent method.

For example:

  1. abstract class Animal
  2. # Returns the name of `self`.
  3. abstract def name : String
  4. end
  5. class Unicorn < Animal
  6. def name : String
  7. "unicorn"
  8. end
  9. end

The documentation for Unicorn#name would be:

  1. Description copied from class `Animal`
  2. Returns the name of `self`.

The child method can use :inherit: to explicitly copy the parent’s documentation, without the Description copied from ... text. :inherit: can also be used to inject the parent’s documentation into additional documentation on the child.

For example:

  1. abstract class Parent
  2. # Some documentation common to every *id*.
  3. abstract def id : Int32
  4. end
  5. class Child < Parent
  6. # Some documentation specific to *id*'s usage within `Child`.
  7. #
  8. # :inherit:
  9. def id : Int32
  10. -1
  11. end
  12. end

The documentation for Child#id would be:

  1. Some documentation specific to *id*'s usage within `Child`.
  2. Some documentation common to every *id*.

note Inheriting documentation only works on instance, non-constructor methods.

A Complete Example

  1. # A unicorn is a **legendary animal** (see the `Legendary` module) that has been
  2. # described since antiquity as a beast with a large, spiraling horn projecting
  3. # from its forehead.
  4. #
  5. # To create a unicorn:
  6. #
  7. #

unicorn = Unicorn.new

unicorn.speak

```

#

The above produces:

#

```text

“I’m a unicorn”

```

#

Check the number of horns with #horns.

class Unicorn include Legendary

Creates a unicorn with the specified number of horns.

def initialize(@horns = 1) raise “Not a unicorn” if @horns != 1 end

Returns the number of horns this unicorn has

#

```

Unicorn.new.horns # => 1

```

def horns @horns end

:ditto:

def number_of_horns horns end

Makes the unicorn speak to STDOUT

def speak puts “I’m a unicorn” end

:nodoc:

class Helper end end ```