Improve where chaining docs [ci-skip]
#45352
Conversation
| @@ -722,12 +722,28 @@ def left_outer_joins!(*args) # :nodoc: | |||
| # === no argument | |||
| # | |||
| # If no argument is passed, #where returns a new instance of WhereChain, that | |||
| # can be chained with #not to return a new relation that negates the where clause. | |||
| # can be chained with #not, #missing, or #associated. | |||
There was a problem hiding this comment.
Since these methods are defined on WhereChain, they will actually be rendered as unformatted text, rather than links or inline code. (The current documentation is similarly broken: https://api.rubyonrails.org/v7.0.3/classes/ActiveRecord/QueryMethods.html#method-i-where.)
We can prefix them with WhereChain:
| # can be chained with #not, #missing, or #associated. | |
| # can be chained with WhereChain#not, WhereChain#missing, or WhereChain#associated. |
Or we can use rdoc-ref links:
| # can be chained with #not, #missing, or #associated. | |
| # can be chained with {not}[rdoc-ref:WhereChain#not], | |
| # {missing}[rdoc-ref:WhereChain#missing], or | |
| # {associated}[rdoc-ref:WhereChain#associated]. |
The former are more verbose when rendered, but the latter are not rendered as inline code (i.e. no highlight, no monospace). I think I lean towards the former.
There was a problem hiding this comment.
Drive-by thought inspired by the above comment, without having actually reviewed the PR: "chained with #not" -> "chained as {where.not}[rdoc-ref..]"? (I don't recall, but assume from context, that we can't get both monospace and a custom link in rdoc?)
There was a problem hiding this comment.
I don't recall, but assume from context, that we can't get both monospace and a custom link in rdoc?
At least, I have not figured out how to do so. From memory, the following didn't work:
{<tt>method_name</tt>}[rdoc-ref:...]{+method_name+}[rdoc-ref:...]<tt>{method_name}[rdoc-ref:...]</tt>(=> rendered literally as code)+{method_name}[rdoc-ref:...]+(=> exceeds the limited support for quoting with+)
There was a problem hiding this comment.
Should we open an issue on rdoc for this? It seems like this would be pretty useful
There was a problem hiding this comment.
@skipkayhil Go for it! 🚀 I had added an item on my TODO list to investigate and potentially submit a PR, but I don't know when or if I would get to it.
ghiculescu
force-pushed
the
wherechain-docs
branch
from
00eab30
to
93d001b
Compare
|
Thanks @jonathanhefner - I updated accordingly. Good call. Is there an easy way to test what the rdoc will come out looking like? |
Locally? You can run |
jonathanhefner
changed the title
where chaining docswhere chaining docs [ci-skip]
https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where only discusses `where.not` in the "no argument" section. A `WhereChain` accepts `not`, `missing`, or `associated`, but you have to click through to https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods/WhereChain.html to learn that. So this PR just updates the docs in https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where to discuss all the chaining options. Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>
ghiculescu
force-pushed
the
wherechain-docs
branch
from
29f5e6b
to
095036c
Compare
|
Thank you, @ghiculescu! 🙌 (Backported to |
Improve `where` chaining docs [ci-skip] (cherry picked from commit 962a1dd)
https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where only discusses
where.notin the "no argument" section. AWhereChainacceptsnot,missing, orassociated, but you have to click through to https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods/WhereChain.html to learn that.This PR just updates the docs in https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where to discuss all the chaining options.