crystal-lang/crystal

Missing inherited methods sections

Blacksmoke16 opened this issue · 3 comments

Blacksmoke16 commented

I think this is a regression from #14910, but haven't expcliitly confirmed it yet. Basically a repeat of #14878 (comment).

On latest 1.13 release: https://crystal-lang.org/api/1.13.3/Array.html, you can see the Included Modules section and related methods inherited from ... sections from those modules at the end of the method summaries.

However on master: https://crystal-lang.org/api/master/Array.html, Included Modules and the inherited methods sections of those modules are missing.

spuun commented

Yes, seems to be related to #14910, that it's exposing a bug for Crystal::Doc::Generator#must_include?. I don't think it's handling generic types correct.

Adding

  def must_include?(type : Crystal::GenericInstanceType)
    type = self.type(type.generic_type)
    must_include? type
  end

seems to do the trick.

  • ❤️1
straight-shoota commented

For future reference: I compared the doc output from #15055 against master using diff on index.json.

$ git checkout master
$ make docs
$ mv docs docs-master
$ git checkout $branch
$ make crystal docs
$ diff <(jq 'del(.. | .url?)' docs-master/index.json) <(jq 'del(.. | .url?)' docs/index.json)

jq 'del(.. | .url?)' pretty prints the JSON for line-based diffing, and it removes all url attributes because they differ between every commit (they are permalinks to the specific commit version of the source file).

I haven't found an easy way to compare the HTML output. There's a lot more noise there and harder to filter out. index.json should usually be fine to assess doc generator content output.

  • 👍2
straight-shoota commented

We're unable to provide a quick fix in #15055 (see #15055 (comment))
I think it's best to revert #14910 (sadly, again after #14908 😢) and work on a fully functional patch. It probably won't make it into 1.14.0 but that's not the end of the world. We've lived with this issue long enough that we can do a bit longer.