RFC: Extending API Docs and Compiler Semantic Output

Crystal Contrib
21

Conceptually it would be easier not to transfer doc status from nested elements to their parents. I think this could get quite nasty.

If MyLib.my_func is to be documented, both MyLib and my_func need to be documented. The latter would obviously be implicitly documented when its parent namespace is.

Maybe a lib function is not an ideal example because its nodoc by default and if it gets documented, it probably doesn’t make much sense to expose only a subset of its fun definitions.

Let’s take a different example with explicit :nodoc::

# :nodoc:
module Foo
  # :doc:
  private def self.foo
  end
end

IMO Foo.foo should not be documented because the entire namespace is undocumented.
The doc generator might produce an error or warning on this constellation (or leave it to a linter).

3 Likes