This page is no longer maintained — Please continue to the home page at www.scala-lang.org

Example Issue with Scala API Documentation and Scala Complexity

61 replies
kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
I was trying to figure out how to start up a process and capture and went to
etc., but I really could not fathom how to do what I wanted by reading the API docs. They are considerably more complex than similar javadoc, and there are no examples. Eventually after quite a bit of time trying the right phrases in Google search, and finding many dead-ends and inappropriate legacy stuff that was misleading, I found
and the solution was immediately obvious. A picture really is worth a thousand words! It would be ever so helpful if the example presented on this web page could be added as an example in the scaladoc for ProcessLogger.
val logger = ProcessLogger(
    (o: String) => println("out " + o),
    (e: String) => println("err " + e))
is significantly more helpful than
def err (s: ⇒ String): Unit

Will be called with each line read from the process error stream.

def out (s: ⇒ String): Unit

Will be called with each line read from the process output stream.

I am a casual user of Scala, and between the scaladoc and Google searching, and rereading "Programming in Scala" - it was significantly more work than trying to figure out the equivalent functionality in Java.

Having more good examples in the scaladoc would make learning and using Scala much more painless. I would update the scaladoc myself, if I knew how. Is it appropriate for me to enter solutions like this in JIRA?

Cheers, Eric
d_m
Joined: 2010-11-11,
User offline. Last seen 35 weeks 2 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On Mon, Nov 28, 2011 at 02:08:03PM -0800, Eric Kolotyluk wrote:
> Having more good examples in the scaladoc would make learning and
> using Scala much more painless. I would update the scaladoc myself,
> if I knew how. Is it appropriate for me to enter solutions like this
> in JIRA?

Hi Eric,

I am excited to help you learn how to help improve the Scala
documentation yourself!

The easiest way to submit documentation improvements is to:

1. fork scala/scala on Github (https://github.com/scala/scala) [1]
2. make documentation changes and push them to your fork
3. open a ticket in JIRA explaining what was added/changed [2]
4. submit pull requests to scala/scala on Github, referencing ticket

I have personally used this workflow to add documentation to Scala (see
for instance the nightly documentation for Ordering [3]).

It's worth noting that Heather Miller at EPFL has been managing
documentation, and in particular coordinating Scala docsprees which
have done a lot to improve the Scala documentation, and are ongoing. So
keep you ears open--they are a great way to get involved, especially if
you are new to contributing to Scala.

Everyone acknowledges that the documentation could be better, more
complete, etc. and the folks at EPFL/Typesafe are very glad to have
help with this, so please feel free to work with all of us to update
Scala's documentation. Managing documentation is exactly the sort of
the thing an open-source community is good at.

Thanks for your interest!

kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple

Done!

Thanks for workflow. Hopefully I followed your instructions correctly.
If so I'll make some more attempts to improve the documentation as I
encounter them.

The usual situation for me is that it can take an hour or more to figure
out how to do something correctly because there are few or no examples
to follow. When I figure things out I might as well document the working
examples I find :-)

kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple

Done!

Thanks for workflow. Hopefully I followed your instructions correctly.
If so I'll make some more attempts to improve the documentation as I
encounter them.

The usual situation for me is that it can take an hour or more to figure
out how to do something correctly because there are few or no examples
to follow. When I figure things out I might as well document the working
examples I find :-)

egon
Joined: 2010-03-17,
User offline. Last seen 2 years 30 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple

It would be nice if there was a link to this workflow on every page of the scaladoc. Something like "How to submit documentation improvements"

+1

2011/11/29 Eric Kolotyluk <eric [dot] kolotyluk [at] gmail [dot] com>
Done!

Thanks for workflow. Hopefully I followed your instructions correctly. If so I'll make some more attempts to improve the documentation as I encounter them.

The usual situation for me is that it can take an hour or more to figure out how to do something correctly because there are few or no examples to follow. When I figure things out I might as well document the working examples I find :-)
Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple

Note that ProcessIO leaks file descriptors, I assume that ProcessLogger
suffers the same flaw.

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

Fair enough, but what do you think of the *current* documentation?

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...

On Mon, Nov 28, 2011 at 20:08, Eric Kolotyluk wrote:
> I was trying to figure out how to start up a process and capture and went to
>
> http://www.scala-lang.org/api/current/index.html#scala.sys.process.Process
> http://www.scala-lang.org/api/current/index.html#scala.sys.process.Proce...
> http://www.scala-lang.org/api/current/index.html#scala.sys.process.Proce...
>
> etc., but I really could not fathom how to do what I wanted by reading the
> API docs. They are considerably more complex than similar javadoc, and there
> are no examples. Eventually after quite a bit of time trying the right
> phrases in Google search, and finding many dead-ends and inappropriate
> legacy stuff that was misleading, I found
>
> http://stackoverflow.com/questions/5563439/grabbing-process-stderr-in-scala
>
> and the solution was immediately obvious. A picture really is worth a
> thousand words! It would be ever so helpful if the example presented on this
> web page could be added as an example in the scaladoc for ProcessLogger.
>
> val logger = ProcessLogger(
> (o: String) => println("out " + o),
> (e: String) => println("err " + e))
>
> is significantly more helpful than
>
> def err (s: => String): Unit
>
> Will be called with each line read from the process error stream.
>
> def out (s: => String): Unit
>
> Will be called with each line read from the process output stream.
>
> I am a casual user of Scala, and between the scaladoc and Google searching,
> and rereading "Programming in Scala" - it was significantly more work than
> trying to figure out the equivalent functionality in Java.
>
> Having more good examples in the scaladoc would make learning and using
> Scala much more painless. I would update the scaladoc myself, if I knew how.
> Is it appropriate for me to enter solutions like this in JIRA?
>
> Cheers, Eric
>

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

Fair enough, but what do you think of the *current* documentation?

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...

On Mon, Nov 28, 2011 at 20:08, Eric Kolotyluk wrote:
> I was trying to figure out how to start up a process and capture and went to
>
> http://www.scala-lang.org/api/current/index.html#scala.sys.process.Process
> http://www.scala-lang.org/api/current/index.html#scala.sys.process.Proce...
> http://www.scala-lang.org/api/current/index.html#scala.sys.process.Proce...
>
> etc., but I really could not fathom how to do what I wanted by reading the
> API docs. They are considerably more complex than similar javadoc, and there
> are no examples. Eventually after quite a bit of time trying the right
> phrases in Google search, and finding many dead-ends and inappropriate
> legacy stuff that was misleading, I found
>
> http://stackoverflow.com/questions/5563439/grabbing-process-stderr-in-scala
>
> and the solution was immediately obvious. A picture really is worth a
> thousand words! It would be ever so helpful if the example presented on this
> web page could be added as an example in the scaladoc for ProcessLogger.
>
> val logger = ProcessLogger(
> (o: String) => println("out " + o),
> (e: String) => println("err " + e))
>
> is significantly more helpful than
>
> def err (s: => String): Unit
>
> Will be called with each line read from the process error stream.
>
> def out (s: => String): Unit
>
> Will be called with each line read from the process output stream.
>
> I am a casual user of Scala, and between the scaladoc and Google searching,
> and rereading "Programming in Scala" - it was significantly more work than
> trying to figure out the equivalent functionality in Java.
>
> Having more good examples in the scaladoc would make learning and using
> Scala much more painless. I would update the scaladoc myself, if I knew how.
> Is it appropriate for me to enter solutions like this in JIRA?
>
> Cheers, Eric
>

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On Tue, Nov 29, 2011 at 06:58, Alan Burlison wrote:
> Note that ProcessIO leaks file descriptors, I assume that ProcessLogger
> suffers the same flaw.

Does it? Last time I checked, I didn't see any place where file
descriptors were leaked. Given that it is used on SBT, a fd leak would
be rather visible, I think.

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On Tue, Nov 29, 2011 at 06:58, Alan Burlison wrote:
> Note that ProcessIO leaks file descriptors, I assume that ProcessLogger
> suffers the same flaw.

Does it? Last time I checked, I didn't see any place where file
descriptors were leaked. Given that it is used on SBT, a fd leak would
be rather visible, I think.

Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 29/11/2011 11:53, Daniel Sobral wrote:

> On Tue, Nov 29, 2011 at 06:58, Alan Burlison wrote:
>> Note that ProcessIO leaks file descriptors, I assume that ProcessLogger
>> suffers the same flaw.
>
> Does it? Last time I checked, I didn't see any place where file
> descriptors were leaked. Given that it is used on SBT, a fd leak would
> be rather visible, I think.

Which, ProcessIO or ProcessLogger? However, they both do.

http://www.scala-lang.org/node/10243

----------
scala> Process("ls").run(new ProcessIO(in => {}, out => {}, err =>
{})).exitValue

Before:

$ pfiles 7355 | egrep 'IFIFO '
$

After run 1:

$ pfiles 7355 | egrep 'IFIFO '
6: S_IFIFO mode:0000 dev:552,0 ino:58944 uid:37845 gid:10 size:0
7: S_IFIFO mode:0000 dev:552,0 ino:58945 uid:37845 gid:10 size:34
9: S_IFIFO mode:0000 dev:552,0 ino:58946 uid:37845 gid:10 size:0
$

After run 2:

$ pfiles 7355 | egrep 'IFIFO '
6: S_IFIFO mode:0000 dev:552,0 ino:58944 uid:37845 gid:10 size:0
7: S_IFIFO mode:0000 dev:552,0 ino:58945 uid:37845 gid:10 size:34
8: S_IFIFO mode:0000 dev:552,0 ino:58953 uid:37845 gid:10 size:0
9: S_IFIFO mode:0000 dev:552,0 ino:58946 uid:37845 gid:10 size:0
10: S_IFIFO mode:0000 dev:552,0 ino:58954 uid:37845 gid:10 size:34
12: S_IFIFO mode:0000 dev:552,0 ino:58955 uid:37845 gid:10 size:0
$
----------

----------
scala> Process("ls").run(ProcessLogger(out => {}, err => {})).exitValue

After run 1:

$ pfiles 7494 | egrep 'IFIFO '
6: S_IFIFO mode:0000 dev:552,0 ino:59313 uid:37845 gid:10 size:0
7: S_IFIFO mode:0000 dev:552,0 ino:59314 uid:37845 gid:10 size:0
9: S_IFIFO mode:0000 dev:552,0 ino:59315 uid:37845 gid:10 size:0

After run 2:

$ pfiles 7494 | egrep 'IFIFO '
6: S_IFIFO mode:0000 dev:552,0 ino:59313 uid:37845 gid:10 size:0
7: S_IFIFO mode:0000 dev:552,0 ino:59314 uid:37845 gid:10 size:0
8: S_IFIFO mode:0000 dev:552,0 ino:59322 uid:37845 gid:10 size:0
9: S_IFIFO mode:0000 dev:552,0 ino:59315 uid:37845 gid:10 size:0
10: S_IFIFO mode:0000 dev:552,0 ino:59323 uid:37845 gid:10 size:0
12: S_IFIFO mode:0000 dev:552,0 ino:59324 uid:37845 gid:10 size:0

After run 3:

$ pfiles 7494 | egrep 'IFIFO '
6: S_IFIFO mode:0000 dev:552,0 ino:59313 uid:37845 gid:10 size:0
7: S_IFIFO mode:0000 dev:552,0 ino:59314 uid:37845 gid:10 size:0
8: S_IFIFO mode:0000 dev:552,0 ino:59322 uid:37845 gid:10 size:0
9: S_IFIFO mode:0000 dev:552,0 ino:59315 uid:37845 gid:10 size:0
10: S_IFIFO mode:0000 dev:552,0 ino:59323 uid:37845 gid:10 size:0
11: S_IFIFO mode:0000 dev:552,0 ino:59335 uid:37845 gid:10 size:0
12: S_IFIFO mode:0000 dev:552,0 ino:59324 uid:37845 gid:10 size:0
13: S_IFIFO mode:0000 dev:552,0 ino:59336 uid:37845 gid:10 size:0
15: S_IFIFO mode:0000 dev:552,0 ino:59337 uid:37845 gid:10 size:0
$

----------

The following doesn't leak:

scala> var v = Process("ls").run(new ProcessIO(in => {in.close}, out =>
{out.close}, err => {err.close})).exitValue

d_m
Joined: 2010-11-11,
User offline. Last seen 35 weeks 2 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

Eric Kolotyluk wrote:
> Done!
>
> Thanks for workflow. Hopefully I followed your instructions correctly. If
> so I'll make some more attempts to improve the documentation as I encounter
> them.

You're welcome, and thanks for helping improve the documentation.

I sometimes have the same issue, where it takes me a bit to figure out
the expected use case of a particular class/trait/whatever. Giving
concrete examples of usage is almost always really helpful.

On Tue, Nov 29, 2011 at 09:18:08AM +0100, Egon Nijns wrote:
> It would be nice if there was a link to this workflow on every page of the
> scaladoc. Something like "How to submit documentation improvements"

I don't know about putting it on every page, but I will try to add (or
update) a page about contributing documentation to the Scala wiki, both
in terms of workflow and maybe also a link to some info about Scaladoc.

In this case, I think there is already some material available (on
contributing, github, scaladoc, etc) but I think it is a bit too spread
out and hard to find at the moment.

kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 2011-11-29 12:58 AM, Alan Burlison wrote:
> Note that ProcessIO leaks file descriptors, I assume that
> ProcessLogger suffers the same flaw.
>

That is an interesting point. Should this type of note or warning also
appear in the official scaladoc?

My gut feeling is - yes - these types of warning should be in the
scaladoc. However, it would be more work as you would have to have a
test case that demonstrates the problem (should the test case also be in
the scaladoc?) and if the problem is ever fixed then the scaladoc needs
to be updated, which sounds like you would need to track the issue in
JIRA. I think it is worth the effort.

I am really amazed at the number of issues similar to this I have seen
in the Scala mailing lists and other forums & blogs. I personally would
appreciate seeing these also appear or be referenced in the scaladocs.

Cheers, Eric

kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 2011-11-29 12:58 AM, Alan Burlison wrote:
> Note that ProcessIO leaks file descriptors, I assume that
> ProcessLogger suffers the same flaw.
>

That is an interesting point. Should this type of note or warning also
appear in the official scaladoc?

My gut feeling is - yes - these types of warning should be in the
scaladoc. However, it would be more work as you would have to have a
test case that demonstrates the problem (should the test case also be in
the scaladoc?) and if the problem is ever fixed then the scaladoc needs
to be updated, which sounds like you would need to track the issue in
JIRA. I think it is worth the effort.

I am really amazed at the number of issues similar to this I have seen
in the Scala mailing lists and other forums & blogs. I personally would
appreciate seeing these also appear or be referenced in the scaladocs.

Cheers, Eric

kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple
  1. I should get in the habit at looking in the nightly docs because this does not appear in the standard docs :-)
  2. That documentation is a good start, but I found it a little intimidating. I would personally be tempted to go in an clarify it once I understood it better - and now I know how to do that ;-)
  3. "This package is used to create process pipelines, similar to Unix command pipelines." is the first line of the scaladoc. I find this misleading because the package is clearly useful if you do not need or want to create process pipelines. I would be tempted to phrase it as "This package is used to create and manage operating system processes, including the ability to create process pipelines, similar to Unix command pipelines."
  4. Given that I am currently in the 'process' ;-) of writing utility scripts in Scala, this is freaking cool! This is very much the type of thing one wants to do when writing utility scripts - invoking a mash-up of other tools and applications.
  5. http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html#scala.sys.process.ProcessBuilder explains things a little better with more details, but is IMHO too focused on pipelines and should have a balance of focus on pipeline use as well as non-pipeline use.
  6. Does Scala have the convention of tutorial pages like Java, where the javadoc often refers the reader to a wider discussion of the subject material in order to keep the javadoc more a reference material? In the case of Scala I would hope the references point to the Scala Wiki.
Cheers, Eric

On 2011-11-29 3:51 AM, Daniel Sobral wrote:
bgFmw [at] mail [dot] gmail [dot] com" type="cite">
Fair enough, but what do you think of the *current* documentation?

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html#scala.sys.process.package

On Mon, Nov 28, 2011 at 20:08, Eric Kolotyluk eric [dot] kolotyluk [at] gmail [dot] com (<eric [dot] kolotyluk [at] gmail [dot] com>) wrote:
I was trying to figure out how to start up a process and capture and went to

http://www.scala-lang.org/api/current/index.html#scala.sys.process.Process
http://www.scala-lang.org/api/current/index.html#scala.sys.process.ProcessBuilder
http://www.scala-lang.org/api/current/index.html#scala.sys.process.ProcessLogger

etc., but I really could not fathom how to do what I wanted by reading the
API docs. They are considerably more complex than similar javadoc, and there
are no examples. Eventually after quite a bit of time trying the right
phrases in Google search, and finding many dead-ends and inappropriate
legacy stuff that was misleading, I found

http://stackoverflow.com/questions/5563439/grabbing-process-stderr-in-scala

and the solution was immediately obvious. A picture really is worth a
thousand words! It would be ever so helpful if the example presented on this
web page could be added as an example in the scaladoc for ProcessLogger.

val logger = ProcessLogger(
    (o: String) => println("out " + o),
    (e: String) => println("err " + e))

is significantly more helpful than

def err (s: => String): Unit

Will be called with each line read from the process error stream.

def out (s: => String): Unit

Will be called with each line read from the process output stream.

I am a casual user of Scala, and between the scaladoc and Google searching,
and rereading "Programming in Scala" - it was significantly more work than
trying to figure out the equivalent functionality in Java.

Having more good examples in the scaladoc would make learning and using
Scala much more painless. I would update the scaladoc myself, if I knew how.
Is it appropriate for me to enter solutions like this in JIRA?

Cheers, Eric



Jason Zaugg
Joined: 2009-05-18,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
On Tue, Nov 29, 2011 at 5:18 PM, Eric Kolotyluk <eric [dot] kolotyluk [at] gmail [dot] com> wrote:
  1. Does Scala have the convention of tutorial pages like Java, where the javadoc often refers the reader to a wider discussion of the subject material in order to keep the javadoc more a reference material? In the case of Scala I would hope the references point to the Scala Wiki.
There is a new home for guides/tutorials. Here's how to contribute:
  http://docs.scala-lang.org/contribute.html
-jason
kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple
  1. I should get in the habit at looking in the nightly docs because this does not appear in the standard docs :-)
  2. That documentation is a good start, but I found it a little intimidating. I would personally be tempted to go in an clarify it once I understood it better - and now I know how to do that ;-)
  3. "This package is used to create process pipelines, similar to Unix command pipelines." is the first line of the scaladoc. I find this misleading because the package is clearly useful if you do not need or want to create process pipelines. I would be tempted to phrase it as "This package is used to create and manage operating system processes, including the ability to create process pipelines, similar to Unix command pipelines."
  4. Given that I am currently in the 'process' ;-) of writing utility scripts in Scala, this is freaking cool! This is very much the type of thing one wants to do when writing utility scripts - invoking a mash-up of other tools and applications.
  5. http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html#scala.sys.process.ProcessBuilder explains things a little better with more details, but is IMHO too focused on pipelines and should have a balance of focus on pipeline use as well as non-pipeline use.
  6. Does Scala have the convention of tutorial pages like Java, where the javadoc often refers the reader to a wider discussion of the subject material in order to keep the javadoc more a reference material? In the case of Scala I would hope the references point to the Scala Wiki.
Cheers, Eric

On 2011-11-29 3:51 AM, Daniel Sobral wrote:
bgFmw [at] mail [dot] gmail [dot] com" type="cite">
Fair enough, but what do you think of the *current* documentation?

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html#scala.sys.process.package

On Mon, Nov 28, 2011 at 20:08, Eric Kolotyluk eric [dot] kolotyluk [at] gmail [dot] com (<eric [dot] kolotyluk [at] gmail [dot] com>) wrote:
I was trying to figure out how to start up a process and capture and went to

http://www.scala-lang.org/api/current/index.html#scala.sys.process.Process
http://www.scala-lang.org/api/current/index.html#scala.sys.process.ProcessBuilder
http://www.scala-lang.org/api/current/index.html#scala.sys.process.ProcessLogger

etc., but I really could not fathom how to do what I wanted by reading the
API docs. They are considerably more complex than similar javadoc, and there
are no examples. Eventually after quite a bit of time trying the right
phrases in Google search, and finding many dead-ends and inappropriate
legacy stuff that was misleading, I found

http://stackoverflow.com/questions/5563439/grabbing-process-stderr-in-scala

and the solution was immediately obvious. A picture really is worth a
thousand words! It would be ever so helpful if the example presented on this
web page could be added as an example in the scaladoc for ProcessLogger.

val logger = ProcessLogger(
    (o: String) => println("out " + o),
    (e: String) => println("err " + e))

is significantly more helpful than

def err (s: => String): Unit

Will be called with each line read from the process error stream.

def out (s: => String): Unit

Will be called with each line read from the process output stream.

I am a casual user of Scala, and between the scaladoc and Google searching,
and rereading "Programming in Scala" - it was significantly more work than
trying to figure out the equivalent functionality in Java.

Having more good examples in the scaladoc would make learning and using
Scala much more painless. I would update the scaladoc myself, if I knew how.
Is it appropriate for me to enter solutions like this in JIRA?

Cheers, Eric



kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 2011-11-29 6:04 AM, Erik Osheim wrote:
> Eric Kolotyluk wrote:
>> Done!
>>
>> Thanks for workflow. Hopefully I followed your instructions correctly. If
>> so I'll make some more attempts to improve the documentation as I encounter
>> them.
> You're welcome, and thanks for helping improve the documentation.
>
> I sometimes have the same issue, where it takes me a bit to figure out
> the expected use case of a particular class/trait/whatever. Giving
> concrete examples of usage is almost always really helpful.
>
> On Tue, Nov 29, 2011 at 09:18:08AM +0100, Egon Nijns wrote:
>> It would be nice if there was a link to this workflow on every page of the
>> scaladoc. Something like "How to submit documentation improvements"
> I don't know about putting it on every page, but I will try to add (or
> update) a page about contributing documentation to the Scala wiki, both
> in terms of workflow and maybe also a link to some info about Scaladoc.

I would be happy to review it (from a newbie perspective) for you.

Another place you could put the the "How to submit documentation
improvements" link would be int the search frame. It would not be on
every page but it would be always visible and it might attract more
people into contributing to more documentation improvements (which we
all agree is desirable).

>
> In this case, I think there is already some material available (on
> contributing, github, scaladoc, etc) but I think it is a bit too spread
> out and hard to find at the moment.

I definitely agree :-)

>

Jason Zaugg
Joined: 2009-05-18,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
On Tue, Nov 29, 2011 at 5:18 PM, Eric Kolotyluk <eric [dot] kolotyluk [at] gmail [dot] com> wrote:
  1. Does Scala have the convention of tutorial pages like Java, where the javadoc often refers the reader to a wider discussion of the subject material in order to keep the javadoc more a reference material? In the case of Scala I would hope the references point to the Scala Wiki.
There is a new home for guides/tutorials. Here's how to contribute:
  http://docs.scala-lang.org/contribute.html
-jason
ScottC 2
Joined: 2011-01-30,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Complex

Do these descriptors leak permanently? What happens if you force a
System.gc a couple times?

If the resource management is done via finalizer() or WeakReference
(highly preferred in most situations over finalize()) a GC will have
to occur first.

Waiting for the GC to trigger either of the above resource management
mechanisms is a bad idea. There should be one of the above mechanisms
as a fallback strategy, but normal use should not depend on them.

On Nov 29, 5:15 am, Alan Burlison wrote:
> On 29/11/2011 11:53, Daniel Sobral wrote:
>
> > On Tue, Nov 29, 2011 at 06:58, Alan Burlison  wrote:
> >> Note that ProcessIO leaks file descriptors, I assume that ProcessLogger
> >> suffers the same flaw.
>
> > Does it? Last time I checked, I didn't see any place where file
> > descriptors were leaked. Given that it is used on SBT, a fd leak would
> > be rather visible, I think.
>
> Which, ProcessIO or ProcessLogger?  However, they both do.
>
> http://www.scala-lang.org/node/10243
>
> ----------
> scala> Process("ls").run(new ProcessIO(in => {}, out => {}, err =>
> {})).exitValue
>
> Before:
>
> $ pfiles 7355 | egrep 'IFIFO '
> $
>
> After run 1:
>
> $ pfiles 7355 | egrep 'IFIFO '
>     6: S_IFIFO mode:0000 dev:552,0 ino:58944 uid:37845 gid:10 size:0
>     7: S_IFIFO mode:0000 dev:552,0 ino:58945 uid:37845 gid:10 size:34
>     9: S_IFIFO mode:0000 dev:552,0 ino:58946 uid:37845 gid:10 size:0
> $
>
> After run 2:
>
> $ pfiles 7355 | egrep 'IFIFO '
>     6: S_IFIFO mode:0000 dev:552,0 ino:58944 uid:37845 gid:10 size:0
>     7: S_IFIFO mode:0000 dev:552,0 ino:58945 uid:37845 gid:10 size:34
>     8: S_IFIFO mode:0000 dev:552,0 ino:58953 uid:37845 gid:10 size:0
>     9: S_IFIFO mode:0000 dev:552,0 ino:58946 uid:37845 gid:10 size:0
>    10: S_IFIFO mode:0000 dev:552,0 ino:58954 uid:37845 gid:10 size:34
>    12: S_IFIFO mode:0000 dev:552,0 ino:58955 uid:37845 gid:10 size:0
> $
> ----------
>
> ----------
> scala> Process("ls").run(ProcessLogger(out => {}, err => {})).exitValue
>
> After run 1:
>
> $ pfiles 7494 | egrep 'IFIFO '
>     6: S_IFIFO mode:0000 dev:552,0 ino:59313 uid:37845 gid:10 size:0
>     7: S_IFIFO mode:0000 dev:552,0 ino:59314 uid:37845 gid:10 size:0
>     9: S_IFIFO mode:0000 dev:552,0 ino:59315 uid:37845 gid:10 size:0
>
> After run 2:
>
> $ pfiles 7494 | egrep 'IFIFO '
>     6: S_IFIFO mode:0000 dev:552,0 ino:59313 uid:37845 gid:10 size:0
>     7: S_IFIFO mode:0000 dev:552,0 ino:59314 uid:37845 gid:10 size:0
>     8: S_IFIFO mode:0000 dev:552,0 ino:59322 uid:37845 gid:10 size:0
>     9: S_IFIFO mode:0000 dev:552,0 ino:59315 uid:37845 gid:10 size:0
>    10: S_IFIFO mode:0000 dev:552,0 ino:59323 uid:37845 gid:10 size:0
>    12: S_IFIFO mode:0000 dev:552,0 ino:59324 uid:37845 gid:10 size:0
>
> After run 3:
>
> $ pfiles 7494 | egrep 'IFIFO '
>     6: S_IFIFO mode:0000 dev:552,0 ino:59313 uid:37845 gid:10 size:0
>     7: S_IFIFO mode:0000 dev:552,0 ino:59314 uid:37845 gid:10 size:0
>     8: S_IFIFO mode:0000 dev:552,0 ino:59322 uid:37845 gid:10 size:0
>     9: S_IFIFO mode:0000 dev:552,0 ino:59315 uid:37845 gid:10 size:0
>    10: S_IFIFO mode:0000 dev:552,0 ino:59323 uid:37845 gid:10 size:0
>    11: S_IFIFO mode:0000 dev:552,0 ino:59335 uid:37845 gid:10 size:0
>    12: S_IFIFO mode:0000 dev:552,0 ino:59324 uid:37845 gid:10 size:0
>    13: S_IFIFO mode:0000 dev:552,0 ino:59336 uid:37845 gid:10 size:0
>    15: S_IFIFO mode:0000 dev:552,0 ino:59337 uid:37845 gid:10 size:0
> $
>
> ----------
>
> The following doesn't leak:
>
> scala> var v = Process("ls").run(new ProcessIO(in => {in.close}, out =>
> {out.close}, err => {err.close})).exitValue
>
> --
> Alan Burlison
> --

Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Example Issue with Scala API Documentation and Scala Co

On 29/11/2011 17:58, ScottC wrote:

> Do these descriptors leak permanently? What happens if you force a
> System.gc a couple times?

It's nothing to do with GC. ProcessIO uses Source and Source doesn't do
auto-cleanup of file descriptors. It's a well-known problem - well,
well-known once you know to go look for it, at least.

http://stackoverflow.com/questions/1762843/why-doesnt-scala-source-close...

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala Co

On Tue, Nov 29, 2011 at 16:21, Alan Burlison wrote:
> On 29/11/2011 17:58, ScottC wrote:
>
>> Do these descriptors leak permanently?  What happens if you force a
>> System.gc a couple times?
>
> It's nothing to do with GC.  ProcessIO uses Source and Source doesn't do
> auto-cleanup of file descriptors.  It's a well-known problem - well,
> well-known once you know to go look for it, at least.
>
> http://stackoverflow.com/questions/1762843/why-doesnt-scala-source-close...

But the Source that is used by ProcessIO is *NOT* scala.io.Source. It
is scala.sys.process.ProcessBuilder.Source -- an altogether different
beast.

Besides, Source doesn't "leak" file descriptors -- it just doesn't
close them automatically.

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On Tue, Nov 29, 2011 at 11:15, Alan Burlison wrote:
> On 29/11/2011 11:53, Daniel Sobral wrote:
>
>> On Tue, Nov 29, 2011 at 06:58, Alan Burlison
>>  wrote:
>>>
>>> Note that ProcessIO leaks file descriptors, I assume that ProcessLogger
>>> suffers the same flaw.
>>
>> Does it? Last time I checked, I didn't see any place where file
>> descriptors were leaked. Given that it is used on SBT, a fd leak would
>> be rather visible, I think.
>
> Which, ProcessIO or ProcessLogger?  However, they both do.
>
> http://www.scala-lang.org/node/10243

I've looked at it, and there's a lot of care taken to close the
streams used on the pipes. I wonder if the idea with ProcessIO is just
that the user should take care of closing them at the proper time
(which is hard, given the awkward interface). I'm more interested if
it leaks file descriptors when used with things like lines, !!, etc,
which _don't_ give you any chance of closing anything.

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On Tue, Nov 29, 2011 at 11:15, Alan Burlison wrote:
> On 29/11/2011 11:53, Daniel Sobral wrote:
>
>> On Tue, Nov 29, 2011 at 06:58, Alan Burlison
>>  wrote:
>>>
>>> Note that ProcessIO leaks file descriptors, I assume that ProcessLogger
>>> suffers the same flaw.
>>
>> Does it? Last time I checked, I didn't see any place where file
>> descriptors were leaked. Given that it is used on SBT, a fd leak would
>> be rather visible, I think.
>
> Which, ProcessIO or ProcessLogger?  However, they both do.
>
> http://www.scala-lang.org/node/10243

I've looked at it, and there's a lot of care taken to close the
streams used on the pipes. I wonder if the idea with ProcessIO is just
that the user should take care of closing them at the proper time
(which is hard, given the awkward interface). I'm more interested if
it leaks file descriptors when used with things like lines, !!, etc,
which _don't_ give you any chance of closing anything.

Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Example Issue with Scala API Documentation and Scala Co

On 30/11/2011 00:02, Daniel Sobral wrote:

> But the Source that is used by ProcessIO is *NOT* scala.io.Source. It
> is scala.sys.process.ProcessBuilder.Source -- an altogether different
> beast.

That just happen to share the same name. How ... helpful.

> Besides, Source doesn't "leak" file descriptors -- it just doesn't
> close them automatically.

It doesn't document that behaviour, so unless you happen to know about
it it's pretty certain you are going to end up with a FD leak. Sure
it's easy enough to add a close() but it should be in the docs, and it
isn't.

Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 30/11/2011 00:52, Daniel Sobral wrote:

> I've looked at it, and there's a lot of care taken to close the
> streams used on the pipes. I wonder if the idea with ProcessIO is just
> that the user should take care of closing them at the proper time
> (which is hard, given the awkward interface). I'm more interested if
> it leaks file descriptors when used with things like lines, !!, etc,
> which _don't_ give you any chance of closing anything.

Aren't those methods on ProcessBuilder rather than ProcessIO? I did
look at ProcessBuilder but I needed to feed the output into the XML
parser classes so I ended up just using Process and ProcessIO directly.
Plus I don't really like the ProcessBuilder interface, although that's
purely a personal taste thing - I can accept that other people think it
is neat.

Naftoli Gugenheim
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple


On Mon, Nov 28, 2011 at 5:41 PM, Erik Osheim <erik [at] plastic-idolatry [dot] com> wrote:
The easiest way to submit documentation improvements is to:
 1. fork scala/scala on Github (https://github.com/scala/scala) [1]
 2. make documentation changes and push them to your fork
 3. open a ticket in JIRA explaining what was added/changed [2]
 4. submit pull requests to scala/scala on Github, referencing ticket


It might be possible to simplify the first two steps. If you navigate to the source file on github, you should be able to click "Fork and edit this file," which will let you edit it right in your browser in a fork. I'm not sure if it will reuse a previous fork you made.

Naftoli Gugenheim
Joined: 2008-12-17,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple


On Mon, Nov 28, 2011 at 5:41 PM, Erik Osheim <erik [at] plastic-idolatry [dot] com> wrote:
The easiest way to submit documentation improvements is to:
 1. fork scala/scala on Github (https://github.com/scala/scala) [1]
 2. make documentation changes and push them to your fork
 3. open a ticket in JIRA explaining what was added/changed [2]
 4. submit pull requests to scala/scala on Github, referencing ticket


It might be possible to simplify the first two steps. If you navigate to the source file on github, you should be able to click "Fork and edit this file," which will let you edit it right in your browser in a fork. I'm not sure if it will reuse a previous fork you made.

Joshua.Suereth
Joined: 2008-09-02,
User offline. Last seen 32 weeks 5 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
Hey guys, we're about to go live with a new github repo.  You may not want to be using the unofficial one in the near future :)
ALSO -
Please don't cross-post to scala-user and scala-debate for discussion.   scala-debate is for discussions, scala-user for "how do I use scala"
- Josh

On Tue, Nov 29, 2011 at 8:54 PM, Naftoli Gugenheim <naftoligug [at] gmail [dot] com> wrote:


On Mon, Nov 28, 2011 at 5:41 PM, Erik Osheim <erik [at] plastic-idolatry [dot] com> wrote:
The easiest way to submit documentation improvements is to:
 1. fork scala/scala on Github (https://github.com/scala/scala) [1]
 2. make documentation changes and push them to your fork
 3. open a ticket in JIRA explaining what was added/changed [2]
 4. submit pull requests to scala/scala on Github, referencing ticket


It might be possible to simplify the first two steps. If you navigate to the source file on github, you should be able to click "Fork and edit this file," which will let you edit it right in your browser in a fork. I'm not sure if it will reuse a previous fork you made.


dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala Co

On Tue, Nov 29, 2011 at 22:52, Alan Burlison wrote:
> On 30/11/2011 00:02, Daniel Sobral wrote:
>
>> But the Source that is used by ProcessIO is *NOT* scala.io.Source. It
>> is scala.sys.process.ProcessBuilder.Source -- an altogether different
>> beast.
>
> That just happen to share the same name.  How ... helpful.

Tell me about it. :-/

>> Besides, Source doesn't "leak" file descriptors -- it just doesn't
>> close them automatically.
>
> It doesn't document that behaviour, so unless you happen to know about it
> it's pretty certain you are going to end up with a FD leak.  Sure it's easy
> enough to add a close() but it should be in the docs, and it isn't.

Yes, sure. And we bloggers are also guilty with our cool one-liners
that don't close the Source.

I'm just making the distinction of a situation where the user _can't_
do anything about it from one where he _should_ be doing something.

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On Tue, Nov 29, 2011 at 23:03, Alan Burlison wrote:
> On 30/11/2011 00:52, Daniel Sobral wrote:
>
>> I've looked at it, and there's a lot of care taken to close the
>> streams used on the pipes. I wonder if the idea with ProcessIO is just
>> that the user should take care of closing them at the proper time
>> (which is hard, given the awkward interface). I'm more interested if
>> it leaks file descriptors when used with things like lines, !!, etc,
>> which _don't_ give you any chance of closing anything.
>
> Aren't those methods on ProcessBuilder rather than ProcessIO?  I did look at
> ProcessBuilder but I needed to feed the output into the XML parser classes
> so I ended up just using Process and ProcessIO directly.  Plus I don't
> really like the ProcessBuilder interface, although that's purely a personal
> taste thing - I can accept that other people think it is neat.

They are not on ProcessIO, that's for sure. They appear on classes
that are actually package-private, so one can't browse them from
Scaladoc. And, on that note, BasicIO was originally private, but
became public when the library was transposed to Scala, for some
reason.

Joshua.Suereth
Joined: 2008-09-02,
User offline. Last seen 32 weeks 5 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
Hey guys, we're about to go live with a new github repo.  You may not want to be using the unofficial one in the near future :)
ALSO -
Please don't cross-post to scala-user and scala-debate for discussion.   scala-debate is for discussions, scala-user for "how do I use scala"
- Josh

On Tue, Nov 29, 2011 at 8:54 PM, Naftoli Gugenheim <naftoligug [at] gmail [dot] com> wrote:


On Mon, Nov 28, 2011 at 5:41 PM, Erik Osheim <erik [at] plastic-idolatry [dot] com> wrote:
The easiest way to submit documentation improvements is to:
 1. fork scala/scala on Github (https://github.com/scala/scala) [1]
 2. make documentation changes and push them to your fork
 3. open a ticket in JIRA explaining what was added/changed [2]
 4. submit pull requests to scala/scala on Github, referencing ticket


It might be possible to simplify the first two steps. If you navigate to the source file on github, you should be able to click "Fork and edit this file," which will let you edit it right in your browser in a fork. I'm not sure if it will reuse a previous fork you made.


kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple
On 2011-11-29 5:54 PM, Naftoli Gugenheim wrote:
CANpg8PBOikVWA8dCJ42GbkSCGiNDHTJbhD82jtPmZmy38T8t1A [at] mail [dot] gmail [dot] com" type="cite">

On Mon, Nov 28, 2011 at 5:41 PM, Erik Osheim <erik [at] plastic-idolatry [dot] com" rel="nofollow">erik [at] plastic-idolatry [dot] com> wrote:
The easiest way to submit documentation improvements is to:
 1. fork scala/scala on Github (https://github.com/scala/scala) [1]
 2. make documentation changes and push them to your fork
 3. open a ticket in JIRA explaining what was added/changed [2]
 4. submit pull requests to scala/scala on Github, referencing ticket


It might be possible to simplify the first two steps. If you navigate to the source file on github, you should be able to click "Fork and edit this file," which will let you edit it right in your browser in a fork. I'm not sure if it will reuse a previous fork you made.

You are correct, that was my experience.

Overall the experience was a little harder than I wanted, but a lot easier than I expected.

Cheers, Eric
kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple
On 2011-11-29 5:54 PM, Naftoli Gugenheim wrote:
CANpg8PBOikVWA8dCJ42GbkSCGiNDHTJbhD82jtPmZmy38T8t1A [at] mail [dot] gmail [dot] com" type="cite">

On Mon, Nov 28, 2011 at 5:41 PM, Erik Osheim <erik [at] plastic-idolatry [dot] com" rel="nofollow">erik [at] plastic-idolatry [dot] com> wrote:
The easiest way to submit documentation improvements is to:
 1. fork scala/scala on Github (https://github.com/scala/scala) [1]
 2. make documentation changes and push them to your fork
 3. open a ticket in JIRA explaining what was added/changed [2]
 4. submit pull requests to scala/scala on Github, referencing ticket


It might be possible to simplify the first two steps. If you navigate to the source file on github, you should be able to click "Fork and edit this file," which will let you edit it right in your browser in a fork. I'm not sure if it will reuse a previous fork you made.

You are correct, that was my experience.

Overall the experience was a little harder than I wanted, but a lot easier than I expected.

Cheers, Eric
dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On Tue, Nov 29, 2011 at 23:03, Alan Burlison wrote:
> On 30/11/2011 00:52, Daniel Sobral wrote:
>
>> I've looked at it, and there's a lot of care taken to close the
>> streams used on the pipes. I wonder if the idea with ProcessIO is just
>> that the user should take care of closing them at the proper time
>> (which is hard, given the awkward interface). I'm more interested if
>> it leaks file descriptors when used with things like lines, !!, etc,
>> which _don't_ give you any chance of closing anything.
>
> Aren't those methods on ProcessBuilder rather than ProcessIO?  I did look at
> ProcessBuilder but I needed to feed the output into the XML parser classes
> so I ended up just using Process and ProcessIO directly.  Plus I don't
> really like the ProcessBuilder interface, although that's purely a personal
> taste thing - I can accept that other people think it is neat.

They are not on ProcessIO, that's for sure. They appear on classes
that are actually package-private, so one can't browse them from
Scaladoc. And, on that note, BasicIO was originally private, but
became public when the library was transposed to Scala, for some
reason.

Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Example Issue with Scala API Documentation and Scala Co

On 30/11/2011 02:04, Daniel Sobral wrote:

>> It doesn't document that behaviour, so unless you happen to know about it
>> it's pretty certain you are going to end up with a FD leak. Sure it's easy
>> enough to add a close() but it should be in the docs, and it isn't.
>
> Yes, sure. And we bloggers are also guilty with our cool one-liners
> that don't close the Source.
>
> I'm just making the distinction of a situation where the user _can't_
> do anything about it from one where he _should_ be doing something.

Yep, fair point. I suppose this is really just another example of the
very variable quality of the Scala docs.

There really does need to be a better way than Git of adding notes and
annotations to the current docs - I'd be happy to add notes in if it
took just a couple of minutes - I'm thinking of something like the
comment facility that the Mercurial docs use, e.g.
http://hgbook.red-bean.com/read/preface.html

That could also be a source of information to help target the docspree
events - if a page has a lot of comments on it it's an indication that
it probably needs work. Also, asking people to collate and add in
information from comments is far less daunting than a request to
"rewrite a page", especially for people like myself who are new to the
language.

Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 30/11/2011 02:07, Daniel Sobral wrote:

>> Aren't those methods on ProcessBuilder rather than ProcessIO? I did look at
>> ProcessBuilder but I needed to feed the output into the XML parser classes
>> so I ended up just using Process and ProcessIO directly. Plus I don't
>> really like the ProcessBuilder interface, although that's purely a personal
>> taste thing - I can accept that other people think it is neat.
>
> They are not on ProcessIO, that's for sure. They appear on classes
> that are actually package-private, so one can't browse them from
> Scaladoc. And, on that note, BasicIO was originally private, but
> became public when the library was transposed to Scala, for some
> reason.

Ah, that explains it - thanks for the detail, although I think my
thoughts were something along the lines of "Ugh..." :-)

kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 2011-11-30 1:54 AM, Alan Burlison wrote:
> On 30/11/2011 02:07, Daniel Sobral wrote:
>
>>> Aren't those methods on ProcessBuilder rather than ProcessIO? I did
>>> look at
>>> ProcessBuilder but I needed to feed the output into the XML parser
>>> classes
>>> so I ended up just using Process and ProcessIO directly. Plus I don't
>>> really like the ProcessBuilder interface, although that's purely a
>>> personal
>>> taste thing - I can accept that other people think it is neat.
>>
>> They are not on ProcessIO, that's for sure. They appear on classes
>> that are actually package-private, so one can't browse them from
>> Scaladoc. And, on that note, BasicIO was originally private, but
>> became public when the library was transposed to Scala, for some
>> reason.
>
> Ah, that explains it - thanks for the detail, although I think my
> thoughts were something along the lines of "Ugh..." :-)
>

OK, I've been following this subthread, but I cannot figure out the
conclusion.

So, is there anything about Process, ProcessIO or ProcessLogger that
needs to be documented as as warning to to the user?

kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 2011-11-30 1:54 AM, Alan Burlison wrote:
> On 30/11/2011 02:07, Daniel Sobral wrote:
>
>>> Aren't those methods on ProcessBuilder rather than ProcessIO? I did
>>> look at
>>> ProcessBuilder but I needed to feed the output into the XML parser
>>> classes
>>> so I ended up just using Process and ProcessIO directly. Plus I don't
>>> really like the ProcessBuilder interface, although that's purely a
>>> personal
>>> taste thing - I can accept that other people think it is neat.
>>
>> They are not on ProcessIO, that's for sure. They appear on classes
>> that are actually package-private, so one can't browse them from
>> Scaladoc. And, on that note, BasicIO was originally private, but
>> became public when the library was transposed to Scala, for some
>> reason.
>
> Ah, that explains it - thanks for the detail, although I think my
> thoughts were something along the lines of "Ugh..." :-)
>

OK, I've been following this subthread, but I cannot figure out the
conclusion.

So, is there anything about Process, ProcessIO or ProcessLogger that
needs to be documented as as warning to to the user?

ichoran
Joined: 2009-08-14,
User offline. Last seen 2 years 3 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple
Related to the API documentation discussion--Ittay just pointed out a confusing-looking method signature:

def ++ [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]) : That


Although he was focused on a different aspect, I noticed a potential problem with this one. Is there any chance that we can avoid having both a "That" type and a "that" argument of a completely different type?  This is a source change, not a documentation change, but it might make the method signature less impenetrable.

  --Rex

P.S. Sorry--don't have time to make the changes myself, just point out the issue.

Joshua.Suereth
Joined: 2008-09-02,
User offline. Last seen 32 weeks 5 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
"That" is used an awful lot in the collection library, and I agree that better name (like ResultCollection) could be used.  It also helps understand CanBuildFrom ->
CanBuildFrom[List[A], B, ResultCollection] // OH, right, building from List to some other collection, not sure about B yet...
- Josh

On Wed, Nov 30, 2011 at 10:33 AM, Rex Kerr <ichoran [at] gmail [dot] com> wrote:
Related to the API documentation discussion--Ittay just pointed out a confusing-looking method signature:

def ++ [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]) : That


Although he was focused on a different aspect, I noticed a potential problem with this one. Is there any chance that we can avoid having both a "That" type and a "that" argument of a completely different type?  This is a source change, not a documentation change, but it might make the method signature less impenetrable.

  --Rex

P.S. Sorry--don't have time to make the changes myself, just point out the issue.


Kevin Wright 2
Joined: 2010-05-30,
User offline. Last seen 26 weeks 4 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
The whole idea of a type parameter being a constrained *output* following inference...
I remember my own moment of suddenly groking the idea, and know it's a major milestone in really coming to appreciate the power and flexibility of the type system.  So +1 on anything that would make this more intuitive.

On 30 November 2011 15:38, Josh Suereth <joshua [dot] suereth [at] gmail [dot] com> wrote:
"That" is used an awful lot in the collection library, and I agree that better name (like ResultCollection) could be used.  It also helps understand CanBuildFrom ->
CanBuildFrom[List[A], B, ResultCollection] // OH, right, building from List to some other collection, not sure about B yet...
- Josh

On Wed, Nov 30, 2011 at 10:33 AM, Rex Kerr <ichoran [at] gmail [dot] com> wrote:
Related to the API documentation discussion--Ittay just pointed out a confusing-looking method signature:

def ++ [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]) : That


Although he was focused on a different aspect, I noticed a potential problem with this one. Is there any chance that we can avoid having both a "That" type and a "that" argument of a completely different type?  This is a source change, not a documentation change, but it might make the method signature less impenetrable.

  --Rex

P.S. Sorry--don't have time to make the changes myself, just point out the issue.




Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 30/11/2011 15:14, Eric Kolotyluk wrote:

> So, is there anything about Process, ProcessIO or ProcessLogger that
> needs to be documented as as warning to to the user?

ProcessIO at least should document that you need to close the streams it
passes to you.

kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple
On 2011-11-30 7:22 AM, Alan Burlison wrote:
4ED64A1F [dot] 3070100 [at] gmail [dot] com" type="cite">On 30/11/2011 15:14, Eric Kolotyluk wrote:

So, is there anything about Process, ProcessIO or ProcessLogger that
needs to be documented as as warning to to the user?

ProcessIO at least should document that you need to close the streams it passes to you.


Thanks.

To confirm
  1. There is nothing extra about ProcessLogger we should document as a warning.
  2. ProcessLogger does not have the same issue as ProcessIO does.

Cheers, Eric
kolotyluk
Joined: 2010-06-04,
User offline. Last seen 5 weeks 15 hours ago.
Re: Example Issue with Scala API Documentation and Scala Comple
On 2011-11-30 7:22 AM, Alan Burlison wrote:
4ED64A1F [dot] 3070100 [at] gmail [dot] com" type="cite">On 30/11/2011 15:14, Eric Kolotyluk wrote:

So, is there anything about Process, ProcessIO or ProcessLogger that
needs to be documented as as warning to to the user?

ProcessIO at least should document that you need to close the streams it passes to you.


Thanks.

To confirm
  1. There is nothing extra about ProcessLogger we should document as a warning.
  2. ProcessLogger does not have the same issue as ProcessIO does.

Cheers, Eric
ichoran
Joined: 2009-08-14,
User offline. Last seen 2 years 3 weeks ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
I would go with something shorter than ResultCollection; the signatures are long enough already to be hard to parse.  "Result" at most, I'd say.

  --Rex

On Wed, Nov 30, 2011 at 10:38 AM, Josh Suereth <joshua [dot] suereth [at] gmail [dot] com> wrote:
"That" is used an awful lot in the collection library, and I agree that better name (like ResultCollection) could be used.  It also helps understand CanBuildFrom ->
CanBuildFrom[List[A], B, ResultCollection] // OH, right, building from List to some other collection, not sure about B yet...
- Josh

On Wed, Nov 30, 2011 at 10:33 AM, Rex Kerr <ichoran [at] gmail [dot] com> wrote:
Related to the API documentation discussion--Ittay just pointed out a confusing-looking method signature:

def ++ [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]) : That


Although he was focused on a different aspect, I noticed a potential problem with this one. Is there any chance that we can avoid having both a "That" type and a "that" argument of a completely different type?  This is a source change, not a documentation change, but it might make the method signature less impenetrable.

  --Rex

P.S. Sorry--don't have time to make the changes myself, just point out the issue.



Alan Burlison
Joined: 2011-08-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Example Issue with Scala API Documentation and Scala Comple

On 30/11/2011 15:44, Eric Kolotyluk wrote:

> 1. There is nothing extra about ProcessLogger we should document as a
> warning.
> 2. ProcessLogger does not have the same issue as ProcessIO does.

I haven't used ProcessLogger in anger but the test I did yesterday
indicated it has the same problem, and I don't know if you can get at
the filehandles to close them. I'd defer to someone who knows more
about ProcessLogger than I do.

Nate Nystrom 2
Joined: 2011-01-28,
User offline. Last seen 42 years 45 weeks ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
A related issue I have is that it would be nice if one could use the methods in the same way as described in the scaladoc use cases, leaving off the "That" entirely.  For instance, List.map has the use case:
def map [B] (f: (A) => B): List[B]
But, then I try this:
scala> List(1,2,3).map[String](_.toString)<console>:8: error: wrong number of type parameters for method map: [B, That](f: Int => B)(implicit bf: scala.collection.generic.CanBuildFrom[List[Int],B,That])That              List(1,2,3).map[String](_.toString)                             ^
The cleanest way I can think of to do this is to overload _ yet again, so that you'd write:
List(1,2,3).map[String, _](_.toString)
and change the scaladoc for the use case to:
def map [B, _] (f: (A) => B): List[B]

Nate

On 30 Nov 2011, at 16:45, Rex Kerr wrote:
I would go with something shorter than ResultCollection; the signatures are long enough already to be hard to parse.  "Result" at most, I'd say.

  --Rex

On Wed, Nov 30, 2011 at 10:38 AM, Josh Suereth <joshua [dot] suereth [at] gmail [dot] com> wrote:
"That" is used an awful lot in the collection library, and I agree that better name (like ResultCollection) could be used.  It also helps understand CanBuildFrom ->
CanBuildFrom[List[A], B, ResultCollection] // OH, right, building from List to some other collection, not sure about B yet...
- Josh

On Wed, Nov 30, 2011 at 10:33 AM, Rex Kerr <ichoran [at] gmail [dot] com> wrote:
Related to the API documentation discussion--Ittay just pointed out a confusing-looking method signature:

def ++ [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]) : That


Although he was focused on a different aspect, I noticed a potential problem with this one. Is there any chance that we can avoid having both a "That" type and a "that" argument of a completely different type?  This is a source change, not a documentation change, but it might make the method signature less impenetrable.

  --Rex

P.S. Sorry--don't have time to make the changes myself, just point out the issue.




Kevin Wright 2
Joined: 2010-05-30,
User offline. Last seen 26 weeks 4 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C
Except it's not the result, it's the *type* of the result.
I've noticed a definite tendency for newcomers to confuse types and values, so anything which mitigates that risk is rather desirable.

On 30 November 2011 15:45, Rex Kerr <ichoran [at] gmail [dot] com> wrote:
I would go with something shorter than ResultCollection; the signatures are long enough already to be hard to parse.  "Result" at most, I'd say.

  --Rex

On Wed, Nov 30, 2011 at 10:38 AM, Josh Suereth <joshua [dot] suereth [at] gmail [dot] com> wrote:
"That" is used an awful lot in the collection library, and I agree that better name (like ResultCollection) could be used.  It also helps understand CanBuildFrom ->
CanBuildFrom[List[A], B, ResultCollection] // OH, right, building from List to some other collection, not sure about B yet...
- Josh

On Wed, Nov 30, 2011 at 10:33 AM, Rex Kerr <ichoran [at] gmail [dot] com> wrote:
Related to the API documentation discussion--Ittay just pointed out a confusing-looking method signature:

def ++ [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]) : That


Although he was focused on a different aspect, I noticed a potential problem with this one. Is there any chance that we can avoid having both a "That" type and a "that" argument of a completely different type?  This is a source change, not a documentation change, but it might make the method signature less impenetrable.

  --Rex

P.S. Sorry--don't have time to make the changes myself, just point out the issue.





dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C

I'll simplify this for you. If I do even this:

"ls".!

It will leak file descriptors. That is not something to be documented,
it has to be FIXED, because there's no way to close them. I'm trying
to get in touch with Mark Harrah to get a better understanding of it
before I open a ticket, but this is definitely a bug.

On Wed, Nov 30, 2011 at 13:14, Eric Kolotyluk wrote:
> On 2011-11-30 1:54 AM, Alan Burlison wrote:
>>
>> On 30/11/2011 02:07, Daniel Sobral wrote:
>>
>>>> Aren't those methods on ProcessBuilder rather than ProcessIO?  I did
>>>> look at
>>>> ProcessBuilder but I needed to feed the output into the XML parser
>>>> classes
>>>> so I ended up just using Process and ProcessIO directly.  Plus I don't
>>>> really like the ProcessBuilder interface, although that's purely a
>>>> personal
>>>> taste thing - I can accept that other people think it is neat.
>>>
>>> They are not on ProcessIO, that's for sure.  They appear on classes
>>> that are actually package-private, so one can't browse them from
>>> Scaladoc. And, on that note, BasicIO was originally private, but
>>> became public when the library was transposed to Scala, for some
>>> reason.
>>
>> Ah, that explains it - thanks for the detail, although I think my thoughts
>> were something along the lines of "Ugh..." :-)
>>
>
> OK, I've been following this subthread, but I cannot figure out the
> conclusion.
>
> So, is there anything about Process, ProcessIO or ProcessLogger that needs
> to be documented as as warning to to the user?
>
>
>

odersky
Joined: 2008-07-29,
User offline. Last seen 45 weeks 6 days ago.
Re: Re: Example Issue with Scala API Documentation and Scala C


On Wed, Nov 30, 2011 at 4:33 PM, Rex Kerr <ichoran [at] gmail [dot] com> wrote:
Related to the API documentation discussion--Ittay just pointed out a confusing-looking method signature:

def ++ [B >: A, That] (that: TraversableOnce[B])(implicit bf: CanBuildFrom[List[A], B, That]) : That


Although he was focused on a different aspect, I noticed a potential problem with this one. Is there any chance that we can avoid having both a "That" type and a "that" argument of a completely different type?  This is a source change, not a documentation change, but it might make the method signature less impenetrable.

  --Rex

P.S. Sorry--don't have time to make the changes myself, just point out the issue.

I think we have an interest in calling "That" either Result or ResultCollection. That helps indeed clarify signatures and error messages.

Cheers

 -- Martin

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland