Issue #14112 has been updated by stomar (Marcus Stollsteimer).


ana06 (Ana Maria Martinez Gomez) wrote:

> which leads to long style discussions in PRs

Please let's be fair: the "long discussion" that triggered this issue (https://github.com/ruby/ruby/pull/1752#discussion_r151213932) consists essentially of 2 (!) comments from me and one from you (not even very controversial). Calling this a "long discussion" and a waste of time seems a bit strong.

Actually, from what I observe since I follow the issues and PRs, long style discussions (or even _any_ style discussions) do not happen. One reason simply is that documentation PRs are rather scarce, and typically they only fix some typo or add an example.

However, personally I would welcome _some_ basic guidelines, both for Ruby example code and the used RDoc (like e.g. the markup of method arguments). What I currently usually do when improving docs is looking through the affected file or class/module, and use a style similar to the already existing documentation... which is a bit inconvenient. Yet I respect that different maintainers might have different opinions about style, and that there is more than one (good) way to do it. I suppose that most contributors would agree on a major part of the mentioned Ruby style guide rules, anyway; enforcing every single aspect of it with a tool like Rubocop would go too far IMO.

----------------------------------------
Feature #14112: Follow style conventions for Ruby code
https://bugs.ruby-lang.org/issues/14112#change-67852

* Author: ana06 (Ana Maria Martinez Gomez)
* Status: Open
* Priority: Normal
* Assignee: 
* Target version: 
----------------------------------------
The Ruby code in the documentation and in the tests is currently not following any style rules, which leads to long style discussions in PRs as well as making the code more complicate to read and understand.

I would really like that Ruby documentation follows [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide) or equivalently [Rubocop rules](https://github.com/bbatsov/rubocop) as they are driven by the Ruby community and it would be consistent and helpful when developing that Ruby documentation follows it as well.

This way we wouldn't need to discuss anything about style in PRs. And when copying code from the documentation you don't have to modify it afterwards.



-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>