Example Issue with Scala API Documentation and Scala Complexity

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

Re: Example Issue with Scala API Documentation and Scala Comple

Added by Naftoli Gugenheim on 2011-11-30, 02:57


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.

Re: Example Issue with Scala API Documentation and Scala Comple

Added by Naftoli Gugenheim on 2011-11-30, 02:57


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.

Re: Example Issue with Scala API Documentation and Scala Comple

Added by kolotyluk on 2011-11-30, 03:27
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

Re: Example Issue with Scala API Documentation and Scala Comple

Added by kolotyluk on 2011-11-30, 03:17
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

Re: Re: Example Issue with Scala API Documentation and Scala C

Added by Joshua.Suereth on 2011-11-30, 03:17
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.


Re: Re: Example Issue with Scala API Documentation and Scala C

Added by Joshua.Suereth on 2011-11-30, 03:07
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.


Re: Example Issue with Scala API Documentation and Scala Comple

Added by kolotyluk on 2011-11-29, 02:57

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 :-)

Re: Example Issue with Scala API Documentation and Scala Comple

Added by kolotyluk on 2011-11-29, 02:47

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 :-)

Re: Example Issue with Scala API Documentation and Scala Comple

Added by egon on 2011-11-29, 09:47

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 :-)

Re: Example Issue with Scala API Documentation and Scala Comple

Added by d_m on 2011-11-29, 15:07

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.

Re: Example Issue with Scala API Documentation and Scala Comple

Added by kolotyluk on 2011-11-29, 17:47

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 :-)

>

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