[ruby-core:113321] [Ruby master Misc#19613] Add version information to all function documentation
From:
"austin (Austin Ziegler) via ruby-core" <ruby-core@...>
Date:
2023-04-24 02:09:05 UTC
List:
ruby-core #113321
Issue #19613 has been updated by austin (Austin Ziegler). jeremyevans0 (Jeremy Evans) wrote in #note-4: > Ruby solves this problem by generating separate documentation for each version: https://docs.ruby-lang.org/en/ . If you have questions regarding how methods work for the Ruby version you are using, you should look at the appropriate documentation for that Ruby version. I don't think it makes sense to maintain documentation on the complete history of the method for every method Ruby uses, including continuing to document all methods previously removed with how they worked and when they were removed. I think that this is a good idea, but but should be introduced as a feature in RDoc *first* and then added to documentation in a future release of Ruby. I do not necessarily think editing *old* versions at this point ```ruby # This function... # # :deprecated since: 2.6 ``` ```ruby # This function... # # :since: 3.0 ``` > Documentation for older Ruby versions shows both `exist?` and `exists?` for `File`. Ruby 3.2 only documents `exist?`. Additionally, method removal is documented in the release notes for the Ruby version. Yes, but the *deprecation* was earlier than that. If this had been added to the documentation so it would show in both the web-based documentation and in `ri`, there would be fewer objections. Elixir manages this very nicely (but as of right now, it also has not *removed* any deprecated functions because they do not yet see a need for Elixir v2). > I don't think it makes sense to edit 10 year old blog posts to add disclaimers. The page already states "more Semantic Versioning type", implying that it does not fully support semantic version. Note that Ruby does basically follow semantic versioning, except that the major version is the first two sets of digits and the minor version is the third set (so for `3.2.1`, the major version is `3.2` and the minor version is `1`) I agree with you that editing the blog post is not appropriate, but I think that adding tools to improve documentation and encouraging their use in gems as well as in Ruby itself would not be amiss. ---------------------------------------- Misc #19613: Add version information to all function documentation https://bugs.ruby-lang.org/issues/19613#change-102878 * Author: fulldecent (William Entriken) * Status: Closed * Priority: Normal ---------------------------------------- Ruby does not properly support semantic versioning. [1] Therefore, for example, the function File#exist? should specify if this function existed since Ruby 2.0.0, Ruby 3.0.0, Ruby 3.2.0 and if, maybe, Ruby 2.9.4.3.az doesn't support it. In this example, if somebody was using File#exists? and were violated to find their code stopped working with Ruby 3.2.0 they might switch to File#exist?. However by reading the documentation we don't know if File#exist? was just created in 3.2.0 to replace File#exists? or if it was created in 2.0 or 2.4 or whatever. Maybe there is some version like 2.9.8 where File#exist? didn't exist. Maybe everybody else reading this (population bias: people that use Redmine) knows this. But if you are just reading the documentation then you won't know this and you will have a painful experience. Possible solutions: 1. Update https://www.ruby-lang.org/en/news/2013/12/21/ruby-version-policy-changes-with-2-1-0/ and add a red warning at the top: RUBY HAS MADE VIOLATIONS OF SEMANTIC VERSIONING UP TO VERSION 3.2.0 THAT WE WILL NOT CORRECT. BUT STARTING IN 3.2.0 WE HAVE/WILL USE SEMANTIC VERSIONING GOING FORWARD. 2. Update https://www.ruby-lang.org/en/news/2013/12/21/ruby-version-policy-changes-with-2-1-0/ and add a red warning at the top: WE HAVE CHANGED OUR POSITION, AND WE WILL BE "INSPIRED" BY SEMVER BUT MAKE NO COMMITMENT TO USE IT COMPLETELY, WE WILL ABANDON THE WORD "SEMVER" TO AVOID CONFUSION. 3. If #1 is not done: update every function documentation to explain all versions and history notes about what applies to that function (this is what PHP does in their official documetation.) --- [1] https://stackoverflow.com/questions/14351272/undefined-method-exists-for-fileclass-nomethoderror -- https://bugs.ruby-lang.org/ ______________________________________________ ruby-core mailing list -- ruby-core@ml.ruby-lang.org To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org ruby-core info -- https://ml.ruby-lang.org/mailman3/postorius/lists/ruby-core.ml.ruby-lang.org/