[PATCH] Grammar modifications for AR associations docs

+1, nice improvements, applies cleanly.

I do have a small suggestion: we should be using <tt> tags for inline code fragments (or +word+ for single words) instead of double quotes or anything else. It's easier to read, more semantic, and conforms to the rdoc style.

Replying to kampers:

+1, nice improvements, applies cleanly. I do have a small suggestion: we should be using <tt> tags for inline code fragments (or +word+ for single words) instead of double quotes or anything else. It's easier to read, more semantic, and conforms to the rdoc style.

My apologies for not being familiar with who you are by your username, but is that a specific request for me or a general request for the community? I'll make the changes to this and to my other doc patches if that's the official word.

(Also, I had DOCS in the Summary because of a request in ticket #8840. Any reason you removed it?)

Thanks for the help!

Hey Sean, I'm Chris. I'm not on the core team or anything, just trying to help out by verifying your patch so it can get committed. See the page "PatchRequirements" in the Rails wiki for details on that. (I'd link to it here but trac keeps rejecting my comment as spam because of it...)

Sorry for not explaining my change to the summary--basically, the report that the core team uses to find documentation patches just looks for the docs tag in the keywords list. So putting [DOCS] in the summary isn't needed. As far as I know, only [PATCH] gets looked for in that field for reporting. So I just removed it to clean it up. What norbert did in #8840 conflicts with what I'm saying here, but the report doesn't seem to care about that. I think it may just be that a while ago, we used to use [DOCS] for this purpose. (Same thing with the tiny keyword, we used to use [TINY] in the summary instead.)

For the <tt>/+ formatting issue, just have a look at the rdoc documentation itself or the rest of the API docs in the rails trunk... you should see it quite a bit. Setting code in a monospaced font is just one of those documentation best-practices that you see in technical writing all the time. So yeah, it would be nice to have that done for this patch. Feel free to put up a new one, or maybe I'll have some time to do it later on.

Hope this helps!

Trying to post the link again, we'll see if it gets past the filter: http://wiki.rubyonrails.org/rails/pages/PatchRequirements

Definitely a big help. You rock.

I don't know if I'll get to add it to this patch tonight (working on it--I should modify this patch rather than create a new one, right?), but I'll keep it in mind for further patches.

Exactly what should be formatted like that? For instance, should these be monospaced?

• nil
• NULL
• true
• false
• Firm#clients (use tt or +?)

I also see several symbols that are tt'ed, but I wonder if they're one word, which should be +'ed. The one file (associations.rb) is inconsistent in the usage in these cases.

Thanks again for the help, Chris!

I just answered my own question. Wrapping a :symbol in +'s doesn't work.

Yeah, I just monospace anything that could be considered code. So all of your examples would qualify.

The +word+ format works for anything without spaces or punctuation, I think. <tt> works for longer blocks. Not totally sure about that, though. Generate the docs with rake doc:rails and check them out to make sure everything worked like you wanted.

Anyway, there are no hard and fast rules about any of this, so you should do whatever seems the easiest to read and understand. Keep up the good work!

Ok, attached is a patch with the previous edits and the suggested edits. If the new ones aren't accepted, the earlier patch hasn't changed.

I did not put any +'s or tt's in the inline comments as these didn't translate over well and, in the case of tt, made the code less readable.

Thanks again, Chris!

Now that's a patch. Beautiful.

Yeah, I never worry about inline comments because they don't get rdoc'd.

I updated it to trunk as of [7228] for you--some of the line numbers had changed so it gave me some "hunks" when I tried to patch. This one applies cleanly (at least for now :)

Now just gotta get some more +1s in here.

updated patch against [7228]

Updated to fix conflict with [7236]

+1, for putting collection.build in place of #push, and many other changes!

Patch applies, generated doc looks good.

+1

(In [7368]) Formatting, grammar and spelling fixes for the associations documentation. [seanhussey] Closes #8899