Spawn() documentation update request

question
documentation

#1

Hi all. I’m new to the community so pardon me if I’m not posting in the right area or am asking a dumb question. This looked like the best place to start.

My question/request is simple: Could documentation for the spawn() method be updated?

I am doing some work with pipes and threads and ended up using the solution shown here. However, the usage of spawn() is entirely different from the documentation, which seems to indicate that the only thing you can do with spawn is execute a command as a child process.

Base.spawn — Function.

spawn(command)

Run a command object asynchronously, returning the resulting Process object.

source

The documentation makes no mention of being able to pass a StdIOSet or Nullable{ProcessChain} as parameters, which is how the Github issue 11823 used it.

I am new to Julia and working with pipelines in general. Just coming out of some hobbyist-level work with Python, so my experience is limited. However, since spawn() seems so useful, and the code is there, it’d be really nice if the documentation reflected its capabilities and was explained clearly.

Thanks and cheers!


#2

Asking for help is good, but the best way to actually make this happen is to do it yourself. Julia’s documentation is easy to edit (it’s just plain text with some Markdown), and the particular documentation for spawn() is right here. You just need to clone the Julia repo, edit the docs, and open a pull request (we can provide pointers to resources if you’re not familiar with the whole pull request thing).

You’re in a great position to do this right now since it sounds like you’re already familiar with what should go into that documentation. Good luck!


#3

Oh, and the source for the various spawn() methods is here: https://github.com/JuliaLang/julia/blob/c463c1f49872ac3d1b7c0809d00288c119ed0909/base/process.jl#L394

I found that by doing:

julia> @edit spawn(`ls -la`)

#4

That source code is exactly what I found as well.

I wouldn’t mind contributing at all. I am familiar with forking/making pull request as well as Markdown syntax. However, to repeat what I said above, I’m new to both Julia and streams/pipelines so I wouldn’t be able to offer full and complete explanations. Someone would have to come back through and correct me, which doesn’t really help anyone and will confuse those who aren’t familiar with the spawn() method.

I can’t make out why there is this chain::Nullable{ProcessChain}=Nullable{ProcessChain}()) business tacked onto the end of each of the functions/methods, in addition to the stdios::StdIOSet.

To differentiate between the 5 different versions of spawn(), I assume I’d have to know something about OrCmds, AndCmds, ErrOrCmds. I’m more than happy to learn. That’s not the issue. I just don’t need them right now for my usage case. Also, with my quick search for AndCmds not pulling up anything useful or explanatory, it looks like learning about these types will take some care and effort to really do it right.

And then there’s the matter of what is more “Julian.” Again, since I’m new to the language and community, I don’t feel like I’m a great person to say “this is how you should use it” since my experience with spawn has been limited to only what was shown in the Github answer.

I fully understand people are busy and that most programmers dislike documentation. That’s to be expected. The point of this was just that I found something that looked very useful but I don’t know how to use it and instead of requesting some help for my personal use case, I thought others could benefit if there was some more documentation.

… so there’s my excuse, haha. I certainly don’t intend to be rude.


#5

No problem! It’s not wrong to ask for documentation, it’s just that there’s a pretty small set of people who could provide that documentation (I’m not one of them, for example), and most of them are volunteers and are already way too busy. So the chances of it happening are definitely nonzero but might be low.

On the other hand, there’s probably a corollary of Cunningham’s Law which goes something like “the best way to fix the documentation is to open a PR with a partial fix” :wink: Opening a PR and having someone correct you may end up being much more effective than asking for a complete right answer from the start.

But I understand that this isn’t your problem, so the above is just my general opinion.