From: nobu@... Date: 2019-12-10T13:45:40+00:00 Subject: [ruby-core:96188] [Ruby master Misc#16408] Ruby docs list incorrect method signatures for PTY::getpty/PTY::spawn Issue #16408 has been updated by nobu (Nobuyoshi Nakada). Thank you for the report and tests. As for the `option` tests, `PTY.spawn` can fail after `PTY.open`, so could you separate `ensure` or use the block form of `PTY.open`? And as it doesn't seem necessary to be `PTY`, doesn't `IO.pipe` suffice? ---------------------------------------- Misc #16408: Ruby docs list incorrect method signatures for PTY::getpty/PTY::spawn https://bugs.ruby-lang.org/issues/16408#change-83070 * Author: yarmiganosca (Chris Hoffman) * Status: Open * Priority: Normal * Assignee: ---------------------------------------- Ruby documentation says the method signature for `PTY::getpty`/`PTY::spawn` is ``` * PTY.spawn(command_line) { |r, w, pid| ... } * PTY.spawn(command_line) => [r, w, pid] * PTY.spawn(command, arguments, ...) { |r, w, pid| ... } * PTY.spawn(command, arguments, ...) => [r, w, pid] ``` However, running the following command with any Ruby since at least 2.1.9 (and based on git history, I believe since 2.0.0) will demonstrate that these method signatures are incorrect: ``` ruby -rpty -e 'r, w, pid = PTY.spawn({"GREETING" => "hello"}, "echo $GREETING world"); puts r.gets(11); r.close; w.close' ``` (it will output `hello world`) Further testing confirms that, aside from the block, `PTY::spawn` has the same method signature as `Kernel#exec`, `Kernel#system`, `Kernel#spawn`, and `Process::spawn`. This makes sense given that their C implementations all call the C method `rb_execarg_new` to handle the complex argument possibilities they all have to deal with. I have a branch with tests that verify this: https://github.com/yarmiganosca/ruby/tree/fix-PTY-getpty-and-spawn-docs-and-tests Travis isn't running CI on this branch, but I'm assuming that's account related and not an issue with my code, especially since the UI just informs me that I'm not allowed to. I'm happy to also change the docs for `PTY::spawn` in this branch, but I wasn't sure which docs to emulate. The docs for this "family" of methods are inconsistent in how they explain the complicated options available to users: * `Kernel#spawn` explains in full the argument possibilities. * `Kernel#exec` and `Kernel#system` both link to the docs for `Kernel#spawn`. * `Process::spawn` explains in full (I think it might be a copy-paste job from the `Kernel#spawn` docs). * The docs for `IO::popen` (another method that uses the "execargs signature" with some modifications) list, but don't explain all the argument possibilities. They also don't do all that great a job at explaining where the other arguments from `IO::popen`'s signature fit alongside the "execargs signature". So it seems that there isn't consensus on the best way to explain this complex method signature (and modifications of it) to readers of the docs. Like I said, I'm happy to fix the `PTY::spawn` docs in this branch, but I was hoping for some guidance on which of the above documentation approaches to emulate. -- https://bugs.ruby-lang.org/ Unsubscribe: