Documenting a Project
You do document your code, don’t you? Crystal makes that easy: it allows for easy docs in Markdown format. It has no special doc syntax apart from #, so all your comments are documentation. First, read through the guidelines.[43] Now let’s add some doc comments to your mineral project (you did create the exercise, didn’t you?). Here’s an example:
| | require "./mineral/*" |
| | |
| | module Mineral |
| | puts "app mineral is started!" |
| | module Hardness |
| | def data |
| | mohs = {"talc" => 1, "gold" => 2.5, "calcite" => 3, |
| | "apatite" => 5, "corundum" => 9} |
| | end |
| | |
| | def hardness |
| | data[self.name] |
| | end |
| | end |
| | |
| | # Every Mineral has **hardness** (see the `Hardness` module). |
| | # |
| | # To create a standard rocky Mineral: |
| | # |
| | # ``` |
| | # min1 = Mineral.new(108) |
| | # min1.to_s |
| | # ``` |
| | # |
| | # The above produces: |
| | # |
| | # ```text |
| | # "This is a mineral with id 108 and is called rock" |
| | # ``` |
| | # |
| | # Checks the hardness with `#hardness`. |
| | class Mineral |
| | include Hardness |
| | getter id, name |
| | setter crystal_struct |
| | |
| | # Creates a mineral with given parameters |
| | def initialize(@id : Int32, @name : String, @crystal_struct : String) |
| | end |
| | |
| | # Creates a mineral with name "rock", 0 hardness and "unknown" structure |
| | def initialize(@id : Int32) |
| | @name = "rock" |
| | @crystal_struct = "unknown" |
| | end |
| | |
| | # Prints out a description of this mineral |
| | def to_s |
| | puts "This is a mineral with id #{id} and it is called #{name} " |
| | puts "It has #{crystal_struct} as crystal structure" |
| | end |
| | |
| | # Returns object properties in csv-format |
| | def to_csv |
| | "#{id},#{name},#{hardness},#{crystal_struct}" |
| | end |
| | def ==(other : self) |
| | id == other.id |
| | end |
| | |
| | def ==(other) |
| | false |
| | end |
| | |
| | # Returns crystal structure of this mineral |
| | def kind_of_crystal |
| | @crystal_struct |
| | end |
| | |
| | # :nodoc: |
| | class Helper # no docs are created for this class |
| | end # neither for private or protected classes |
| | end |
| | end |
Crystal comes with a built-in documentation generator, which is also used for the language’s own API.[44] To generate documentation for your project, start a terminal and go inside the project root folder. Then type the following:
$ crystal docs
This will create a doc folder containing your project’s documentation website. Start it up with doc/index.html. We show part of the class Mineral page in the figure.
Use the flag keywords BUG, DEPRECATED, FIXME, NOTE, OPTIMIZE, and TODO in your docs. These flags help indicate to yourself or others what still has to be done.