Separation of constructor methods in docs

[Sija]

Simple implementation of idea from issue #4071.

[jhass]

Mmh in general I like this, what I would even more like however is if it also would include any factory methods, so I come to wonder if this wouldn't decrease the visibility of these, since you will no longer scan the class methods in order to discover the ways you can get an instance of the class.

[Sija]

@jhass I'd love to include factory methods as well, alas I couldn't find any decent way to filter them out of regular class method list (except by checking return type which is not that reliable since it might be unset).

[bcardiff]

Maybe we should add something like :nodoc: to set the section.

# :factory:
# :constructor:
# :section=constructor:

[Sija]

👍 for :factory:

[bcardiff]

NB: If a comment is applied to mark as factory, then the subtraction of methods needs to be done on class and instance methods.

class Nat
  # :factory:
  def self.zero
  end

  # :factory:
  def succ
  end
end

[ysbaddaden]

Do we really want to start introducing some documentation-specific annotations?

Instead, what about using the specified return type of class methods (which the type inference already uses)? Maybe it could use the inferred type, too. If a class method of class X returns a X, then it's a factory.

[Sija]

@ysbaddaden Would be perfect, yet return type annotations are not always available IIUC.

[ysbaddaden]

Then specifying return type of factories would have double bonus:

• be inferred by the compiler;
• be explicit in docs.

Eventually, could the doc generator infer types? just like the compiler does (first pass)? that seems doable, to me.

[Sija]

@ysbaddaden I've pushed another commit adding factory methods to the list.

[bcardiff]

@ysbaddaden

Eventually, could the doc generator infer types?

Not necessarily. The type inference act upon invocation. The only invocations could be the one in the specs.

I'm ok with using an explicit return type as a flag to identify factory methods.

[Sija]

Anything more to do here before merging?

[asterite]

@Sija I think this needs a bit more discussion, though initially I really like the idea :-)

[Sija]

@asterite Sure thing, I was a bit too hasty with "before merging" part ;)

[Sija]

Now, when the check is more permissive, singleton methods like Fiber.current will get listed as constructors. To control this behavior we could introduce, in the vein of the first proposal, :nofactory: doc marker.

[Sija]

@asterite any decisions yet?

[asterite]

We can separate new methods. But considering all class method that return self as constructors doesn't sound quite right. Plus, class methods are usually fewer than non-class methods, and most of them are usually constructors, so I'm not sure about this. It will bring a lot of discussions about "what is a constructor".

[Sija]

That's true, there are cases where this distinction can't be done automagically. To combine best of both worlds I'd go for new section titled "Factory methods" in which #new methods are added automatically + :factory: annotation which would allow adding given method to above-mentioned section.

[Sija]

@asterite ping? r we ready for some action? :)

[Sija]

@asterite ping :)

[asterite]

@Sija I like it! Thank you! 🎉