Documenting Crystal code

Code comments that are added to types, methods, macros, and constants are counted as documentation comments. The compiler lets us extract the documentation to create an HTML website to present it. We will get into this later in this chapter.

For a comment to act as documentation, it must be applied directly above the item, without any empty lines. Empty lines are allowed but must also be prefixed with a # symbol so that the comment chain is not broken. Let's look at a simple example:

# This comment is not associated with MyClass.
 
# A summary of what MyClass does.
class MyClass; end

In this example, there are two comments: one is associated with MyClass, while the other is not. The first paragraph should be used as the summary, defining the purpose and functionality of the item. The first paragraph comprises all the text, up to a period or an empty comment line, as shown here:

# This is the summary
# this is still the summary
#
# This is not...