feature: Render mixed-in methods and constants with `--embed-mixins`

[flavorjones]

When --embed-mixins option is set:

• methods from an extended module are documented as singleton methods
• attrs from an extended module are documented as class attributes
• methods from an includeed module are documented as instance methods
• attrs from an includeed module are documented as instance attributes
• constants from an includeed module are documented

Sections are created when needed, and Darkfish's template annotates each of these mixed-in CodeObjects.

This feature is inspired by Yard's option of the same name.

---

Example class:

module IncMod
  # :section: Things That Were Included

  # incmod attribute
  attr :incmod_attr

  # constant via mixin
  INCMOD_CONST = "incmod_const"

  # instance method via mixin
  def incmod_method
    "incmod_method"
  end
end

module ExtMod
  # :section: Things That Were Extended

  # extmod attribute
  attr :extmod_attr

  # class method via mixin
  def extmod_method
    "extmod_method"
  end
end

class Foo
  include IncMod
  extend ExtMod
end

Currently this renders like:

With --embed-mixins it renders like:

[flavorjones]

I've pushed an update to this PR to ensure that code object visibility is respected (which was a bug in the original patch).

[flavorjones]

@aycabta I'm curious if you have feedback on this feature? It's off by default but I think would be a real improvement to standard-library classes like Array that inherit significant functionality from Enumerable.

[flavorjones]

@aycabta This feature is live at https://nokogiri.org/rdoc/Nokogiri/XML/Node.html#method-i-at_css if you'd like to see what it looks like. Is this something you would consider merging?

[flavorjones]

Rebased off v6.5.0.

I still think this is a valuable feature to consider. It's been in use at https://nokogiri.org/rdoc/ for the past year, see https://nokogiri.org/rdoc/Nokogiri/XML/Node.html#method-i-css for example.

[flavorjones]

Rebased again off master. @aycabta @nobu would you consider merging this feature?

[flavorjones]

I've rebased again onto master. I still think this would be a valuable feature to merge. @hsbt @drbrain I would appreciate any feedback you have for me.

[flavorjones]

@hsbt If you get some time to review this, I still think it's a good feature, and it's been live on the nokogiri.org site for several years now.

[flavorjones]

@st0012 Thank you for your review!

How does it affect documentation displayed by ri though?

I hadn't even considered ri as a target, since I don't usually use it. I will explore what's necessary to extend the ri content as well.

[flavorjones]

@st0012 So ri is working out of the box with this.

If I generate the ri files with rdoc --embed-mixins --format=ri then the resulting behavior is what I'd expect, which is that it shows the mixed-in methods under all of the classes.

$ ri at_css
= .at_css

(from /home/flavorjones/code/oss/nokogiri/ri)
=== Implementation from Node
------------------------------------------------------------------------
  at_css(*rules, [namespace-bindings, custom-pseudo-class])

------------------------------------------------------------------------

Search this object for CSS rules, and return only the first match. rules
must be one or more CSS selectors.

See Searchable#css for more information.


(from /home/flavorjones/code/oss/nokogiri/ri)
=== Implementation from NodeSet
------------------------------------------------------------------------
  at_css(*rules, [namespace-bindings, custom-pseudo-class])

------------------------------------------------------------------------

Search this object for CSS rules, and return only the first match. rules
must be one or more CSS selectors.

See Searchable#css for more information.


(from /home/flavorjones/code/oss/nokogiri/ri)
=== Implementation from Searchable
------------------------------------------------------------------------
  at_css(*rules, [namespace-bindings, custom-pseudo-class])

------------------------------------------------------------------------

Search this object for CSS rules, and return only the first match. rules
must be one or more CSS selectors.

See Searchable#css for more information.