Issue #16408 has been updated by yarmiganosca (Chris Hoffman).


Turns out `IO.pipe` would result in `"bar\n"` instead of `"bar\r\n"` (`PTY.open` results in strings that end in `"\r\n"`). Given the rest of the file's test cases all expect strings that end in `"\r\n"`, I thought that sticking to convention would be less confusing for future readers.

----------------------------------------
Misc #16408: Ruby docs list incorrect method signatures for PTY::getpty/PTY::spawn
https://bugs.ruby-lang.org/issues/16408#change-83105

* 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: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>