Enhanced RDoc for JSON.dump #443
Conversation
lib/json/common.rb
Outdated
| # JSON.dump(obj, io = nil, limit = nil) | ||
| # | ||
| # Constructs a \JSON \String from +obj+ by calling | ||
| # JSON.generate(obj, JSON.dump_default_options.merge(:max_nesting => limit)) |
There was a problem hiding this comment.
How about translating this to words? Note: IIRC, JSON is also a module that can be included, so the call sequence isn't necessarily JSON.dump, and it calls generate, which may or may not be JSON.generate depending on how dump is called, right?
There was a problem hiding this comment.
Suggested words, please?
Module/class issue is a serious oversight on my part. The only two example calls in the existing doc use JSON.parse and JSON.generate, and I followed that convention.
This is the last method in JSON that I'm 'enhancing,' and it, like the others, uses the class methods in its examples.
The doc for all the methods should be revised to take the 'duality' into account; the introductory material should also address this.
I suggest we merge with the calls as is for now, and figure out a good way to do better, afterwards.
There was a problem hiding this comment.
I've restored the original first sentence.
|
Thank you. Either @hsbt chooses "Squash commits", or you squash the two commits together. |
|
@hsbt, I think this one's ready to squash and merge. |
|
@marcandre, is there an example of a properly documented class/module I can refer to, so I can see how to doc here? |
I'm not sure there is a "perfect" example I can point to (if I understood your question correctly) |
No description provided.