Support `:param:` and `:return:` tag directives, similar to YARD

[zzak]

See YARD Tags doc for param and return.

This comes from a discussion in rails/rails#13989.

I'd like to define the api for this feature and provide support for the tags within the next minor release of RDoc. We don't have to add immediate support to darkfish, since we only need it for Rails and it can be implemented in SDoc.

[fxn]

Let me expand a little bit.

In principle we would not be really really interested in those specific YARD-like tags.

The problem I have with those tags is that they take a whole line each, piling up when you see the source code, and that they invite users to write telegraphic one-liners to their right that often carry little information.

I think the amount of space they take is not balanced, they do not need that much in my view. And I prefer their description to be written in prose as we do nowadays. That free form allows documentation to be as short or detailed as needed.

The problem I want to tackle is signatures. I want documented types (in a wide sense of the word "type" that includes duck typing as in YARD conventions) to be systematically present and in a predictable way.

My first idea was a special directive :sig:, but I am thinking that :call-seq: allows us to mix types and parameter names in a traditional notation. For example:

multiple_of?(Integer number) → true|false

or

[]=(String|Symbol key, Object value) → Object

Something like that.

Let me play a little bit with that idea.

[drbrain]

I have read some source that uses yard for documentation that makes heavy use of the param directive and it was completely unreadable without generating the documentation.

I find these directives don't support readablility at the source level or good documentation practices.

I think :call-seq: is the better way to go. You can provide ruby-esqe pseudo-code for the method arguments and plain English descriptions that are readable whether you're in your editor or browser.

@fxn I would probably write:

multiple_of? integer -> true or false

And:

call-seq:
  collection[key]  = object

Places +object+ at +key+ in this collection.  If the +key+ is not a Symbol or String a TypeError is raised.

By including the argument types in the prose they will be linked which makes for more navigable documentation as the user does not need to search as much. I think linkability in the method display is poor UI, but that is a separate discussion.

[fxn]

Thanks for the suggestions @drbrain.

Including types in prose is what we do now, but not systematically and most methods do not have it documented. In principle I'd like to try a bit that idea with :call-seq: and see how it reads. It would create a convention/expectation, and would be predictable and concise (compared to the tags approach).

[drbrain]

To follow up, I see nothing wrong with your initial examples.

I want to make it easy to write documentation so you can infer the behavior of RDoc from examples rather than needing a guide of directives to both write and understand the documentation in the source. I find the @param style of Yard intimidating for this reason. I think the RDoc philosophy is more approachable for first-time contributors as there is less to learn.

[ioquatix]

I'm also interested in this. @fxn does this make sense or have you implemented your alternative proposal, or was any other proposal similar to this implemented?

[fxn]

@ioquatix Not really.

In Zeitwerk I adopted my own convention (see @sig tags here for example). Current notation is based on RBS's. I also have @private and @raises.

That captures my personal preferences: I want to document signatures in a compact way, without taking too much vertical space, and for documentation purposes. The meaning of individual parameters, the returned value, and under which conditions are exceptions raised, goes in prose.

[ioquatix]

While I generally understand and respect the rdoc format, inventing custom tags is not sustainable because such an approach does not encourage consistency across projects. Even if we have some limited form of tags, it's probably better to standardise it IMHO.

[ioquatix]

After thinking about this a bit more, I'd say this is a big issue for more advanced usage. For types we have RBS or inline type signatures from @parameter blocks, etc. For language servers that do better integration with documentation, RDoc is lacking in structure which can be interpreted by an automated tool.