Type safe documenting

document-as-interface.md

Abstract

Use the interface to prevent missing documents.

Example

class SomeLib
  module Interface
    abstract def foo : String
    abstract def bar : String
  end

  module Implement
    include Interface

    def foo : String
      "abc"
    end

    def bar : String
      "xyz"
    end
  end

  include Interface
  include Implement
end

class SomeLib::Documented
  include Interface

  def foo : String
    "This returns a value of foo."
  end
end

$ $ crystal test.cr
Showing last frame. Use --error-trace for full trace.

In test.cr:4:18

 4 | abstract def bar : String
                  ^--
Error: abstract `def SomeLib::Interface#bar()` must be implemented by SomeLib::Documented

We could detect lack of documentation as a compilation error!

conclusion

• We can use the interface to prevent missing documents.
• However, it is not practical because it is limited to cases where the return value is of type String.