scala.util.parsing.* - a bit of a mess?

On 02/10/11 00:07, Alan Burlison wrote:
> Is it just me that finds the contents of scala.util.parsing.*
> namespace a bit of a mess?
No it's not just you. I recently needed to parse a grammar with scala,
so I wrote a suitable library -- only took a couple of hours.

On 10/01/11 15:10, Tony Morris wrote:

> No it's not just you. I recently needed to parse a grammar with scala,
> so I wrote a suitable library -- only took a couple of hours.

Which is less time than I've already spent trying to get my head around
the library.

Granted I'd take significantly longer than you to do it from scratch as
I don't have your level of Scala experience, but it shows something is
clearly amiss if a neophyte like myself is seriously considering rolling
my own because it's easier/quicker than trying to use library code.

On Sat, Oct 1, 2011 at 11:07, Alan Burlison wrote:
>
> I think that, at present, the biggest single deficiency across all the Scala
> documentation is in the overview parts.  Given I'm told what 'Foo' is *for*
> and what it's characteristics are I can generally figure out what the
> individual members do, even if the documentation is thin. However without a
> statement of intent I'm generally reduced to reading the source code of each
> class I want to use, and that makes trying to use them tedious in the
> extreme.
>
> Docs folks, please, please, please work on the overviews first.

We have nothing to attach overviews to: Scaladoc ignores comments on
pure packages. Even the "landing page" of Scaladoc was created by
providing an external flag reading from an alternative file.

Personally, I think Scaladoc should get comments on pure packages, but
I recognize that the best way of getting something done in an open
source project is doing it yourself, so I don't keep complaining about
it.

As for parser combinators, the best documentation on them are the
papers written about them. Unfortunate, but true. I did improve the
documentation on Parsers, Parser, RegexParsers and JavaTokenParsers
recently, but I never did anything the other parts of the library, so
I'm not the person to improve on them.

On 10/01/11 15:18, Daniel Sobral wrote:

> We have nothing to attach overviews to: Scaladoc ignores comments on
> pure packages. Even the "landing page" of Scaladoc was created by
> providing an external flag reading from an alternative file.
>
> Personally, I think Scaladoc should get comments on pure packages, but
> I recognize that the best way of getting something done in an open
> source project is doing it yourself, so I don't keep complaining about
> it.

So there's no equivalent to Javadoc's Package-info.java or Package.html?
Seems like a clear deficiency, and a rather odd one to be there in the
first place, considering the Java heritage. However, even the
trait/class/object overview docs are poor, and there's no technical
reason for not fixing those.

> As for parser combinators, the best documentation on them are the
> papers written about them. Unfortunate, but true. I did improve the
> documentation on Parsers, Parser, RegexParsers and JavaTokenParsers
> recently, but I never did anything the other parts of the library, so
> I'm not the person to improve on them.

I've read all the papers I can find. They mainly seem to be written to
explain how the parsers are implemented, they aren't usage documentation.

Scala has some good books but the library documentation is very poor.
That's a big stumbling block once you've digested the books and want to
start writing 'real' things in Scala. I'd say it's one of the major
barriers to entry for Scala.

On Sat, Oct 1, 2011 at 13:03, Alan Burlison wrote:
> On 10/01/11 15:18, Daniel Sobral wrote:
>
>> We have nothing to attach overviews to: Scaladoc ignores comments on
>> pure packages. Even the "landing page" of Scaladoc was created by
>> providing an external flag reading from an alternative file.
>
>>
>> Personally, I think Scaladoc should get comments on pure packages, but
>> I recognize that the best way of getting something done in an open
>> source project is doing it yourself, so I don't keep complaining about
>> it.
>
> So there's no equivalent to Javadoc's Package-info.java or Package.html?
>  Seems like a clear deficiency, and a rather odd one to be there in the
> first place, considering the Java heritage.  However, even the
> trait/class/object overview docs are poor, and there's no technical reason
> for not fixing those.

There's one technical reason: someone has to do it. Well, maybe that's
not "technical", but that's what it comes down to.

A lot has been done, on the technical front, to make it easier for the
community help with this, but most of it has not produced the expected
results. The best effort so has is the Scala DocSpree, which took
place one day before Scalathon this year, and was so successful that
there is now the Monthly Scala Docspree
(https://wiki.scala-lang.org/display/SW/Monthly+Scala+Docspree). The
next Docspree will take place October 15th, and everyone's invited.
All you have to do is reserve a little time anytime that Saturday,
write or improve docs for something, and submit it. For more
information, see the link.

>> As for parser combinators, the best documentation on them are the
>> papers written about them. Unfortunate, but true. I did improve the
>> documentation on Parsers, Parser, RegexParsers and JavaTokenParsers
>> recently, but I never did anything the other parts of the library, so
>> I'm not the person to improve on them.
>
> I've read all the papers I can find.  They mainly seem to be written to
> explain how the parsers are implemented, they aren't usage documentation.

The papers I read certainly did enter a lot into usage examples. I
tried looking up what I read, but my PDFs are a mess and I couldn't
find them.

> Scala has some good books but the library documentation is very poor. That's
> a big stumbling block once you've digested the books and want to start
> writing 'real' things in Scala.  I'd say it's one of the major barriers to
> entry for Scala.

It is a volunteer effort, and the people who can better explain what
is wrong are people like you: the ones having a problem. It is hard
for someone who already know what's inside to see clearly what the
stumbling blocks are.

On the Docspree, many participants choose parts of the library they
don't actually have experience with, and, with the help of REPL,
source code and other sources (including people on ##scala-docspree),
document them based on what they learn about it.

(Shameless plug) May I suggest a look at VisualLangLab? A Scala-oriented tutorial can be found at Rapid Prototyping for Scala Parser Combinators.
Regards, -Sanjay
On Sun, Oct 2, 2011 at 00:10, Daniel Sobral <dcsobral@gmail.com> wrote:

On Sat, Oct 1, 2011 at 13:03, Alan Burlison <alan.burlison@gmail.com> wrote:
> On 10/01/11 15:18, Daniel Sobral wrote:
>
>> We have nothing to attach overviews to: Scaladoc ignores comments on
>> pure packages. Even the "landing page" of Scaladoc was created by
>> providing an external flag reading from an alternative file.
>
>>
>> Personally, I think Scaladoc should get comments on pure packages, but
>> I recognize that the best way of getting something done in an open
>> source project is doing it yourself, so I don't keep complaining about
>> it.
>
> So there's no equivalent to Javadoc's Package-info.java or Package.html?
>  Seems like a clear deficiency, and a rather odd one to be there in the
> first place, considering the Java heritage.  However, even the
> trait/class/object overview docs are poor, and there's no technical reason
> for not fixing those.

There's one technical reason: someone has to do it. Well, maybe that's
not "technical", but that's what it comes down to.

A lot has been done, on the technical front, to make it easier for the
community help with this, but most of it has not produced the expected
results. The best effort so has is the Scala DocSpree, which took
place one day before Scalathon this year, and was so successful that
there is now the Monthly Scala Docspree
(https://wiki.scala-lang.org/display/SW/Monthly+Scala+Docspree). The
next Docspree will take place October 15th, and everyone's invited.
All you have to do is reserve a little time anytime that Saturday,
write or improve docs for something, and submit it. For more
information, see the link.

>> As for parser combinators, the best documentation on them are the
>> papers written about them. Unfortunate, but true. I did improve the
>> documentation on Parsers, Parser, RegexParsers and JavaTokenParsers
>> recently, but I never did anything the other parts of the library, so
>> I'm not the person to improve on them.
>
> I've read all the papers I can find.  They mainly seem to be written to
> explain how the parsers are implemented, they aren't usage documentation.

The papers I read certainly did enter a lot into usage examples. I
tried looking up what I read, but my PDFs are a mess and I couldn't
find them.

> Scala has some good books but the library documentation is very poor. That's
> a big stumbling block once you've digested the books and want to start
> writing 'real' things in Scala.  I'd say it's one of the major barriers to
> entry for Scala.

It is a volunteer effort, and the people who can better explain what
is wrong are people like you: the ones having a problem. It is hard
for someone who already know what's inside to see clearly what the
stumbling blocks are.

On the Docspree, many participants choose parts of the library they
don't actually have experience with, and, with the help of REPL,
source code and other sources (including people on ##scala-docspree),
document them based on what they learn about it.

--
Daniel C. Sobral

I travel to the future all the time.

On Saturday, October 1, 2011 9:18:09 AM UTC-5, Daniel Sobral wrote:

> Docs folks, please, please, please work on the overviews first.

We have nothing to attach overviews to: Scaladoc ignores comments on
pure packages. Even the "landing page" of Scaladoc was created by
providing an external flag reading from an alternative file.

It's been a while (before the current version of Scaladoc), but at one time you could document package objects and have that show up in the HTML. So I would just put in an empty package object into its own file, and attach all the overview doco to that. The biggest problem with this was simply knowing where to click in the HTML to access the documentation.
Ken

Hi Alan,

There's a combinator parsing tutorial here:

http://www.artima.com/pins1ed/combinator-parsing.html

Bill

On Sat, Oct 1, 2011 at 7:07 AM, Alan Burlison wrote:
> Is it just me that finds the contents of scala.util.parsing.* namespace a
> bit of a mess?  For example, what is the difference between
> StandardTokenParsers, StdTokenParsers and TokenParsers?  OK, let's look at
> the documentation:
>
> StandardTokenParsers
> This component provides primitive parsers for the standard tokens defined in
> StdTokens.
>
> StdTokenParsers
> This component provides primitive parsers for the standard tokens defined in
> StdTokens.
>
> TokenParsers
> This is the core component for token-based parsers.
>
> Hmph :-(
>
> From reading the various examples out there I understand how the parser
> framework works in general, but when it comes to writing my own parser I
> have no clear idea where to start building out from.  Something from
> scala.util.parsing.combinator?  Dunno.  What about
> scala.util.parsing.lexical?  Or scala.util.parsing.syntactical?  Or in my
> (non-trivial) grammar do I need bits from one for the lexical part for
> lexing and something else for the syntactic elements?
>
> Frankly the documentation is dreadful - sorry.
>
> There needs to be an overview document that explains what each namespace is
> supposed to denote, what each thing withing the namespace is for and when
> you'd use it.  It doesn't need to be a huge tome, but there does need to be
> *something* and so far I havent found anything - apologies if I've not
> managed to find it.
>
> I think that, at present, the biggest single deficiency across all the Scala
> documentation is in the overview parts.  Given I'm told what 'Foo' is *for*
> and what it's characteristics are I can generally figure out what the
> individual members do, even if the documentation is thin. However without a
> statement of intent I'm generally reduced to reading the source code of each
> class I want to use, and that makes trying to use them tedious in the
> extreme.
>
> Docs folks, please, please, please work on the overviews first.
>
> Thanks,
>
> --
> Alan Burlison
> --
>

On 10/02/11 06:21, Ken McDonald wrote:

> It's been a while (before the current version of Scaladoc), but at one time
> you could document package objects and have that show up in the HTML. So I
> would just put in an empty package object into its own file, and attach all
> the overview doco to that. The biggest problem with this was simply knowing
> where to click in the HTML to access the documentation.

From looking at the 2.9.1 source, the overview documentation for
scala.actors and scala.xml.pull (for example) is indeed being generated
from the comments associated with the package object.

On 10/02/11 08:16, Bill Venners wrote:

> Hi Alan,
>
> There's a combinator parsing tutorial here:
>
> http://www.artima.com/pins1ed/combinator-parsing.html

Thanks, I have the 2nd ed of the book which I assume is very similar.
However that's not really what I am looking for. The book is explaining
the principles behind how the scala parser framework works, it isn't
library documentation. That's not a criticism, explaining how things
work is exactly what the book should be doing, the problem is that the
lbrary documentation often doesn't exist. For example listing 31.1 in
the link above shows how to write a JSON parser based on
JavaTokenParsers, yet there's a scala.util.parsing.json.JSON object in
the library that does it all for you - in practice you'd just use that.
In that particular case there is overview documentation, but in most
of the other cases there isn't.

Hi Alan,

On Sun, Oct 2, 2011 at 3:38 AM, Alan Burlison wrote:
> On 10/02/11 08:16, Bill Venners wrote:
>
>> Hi Alan,
>>
>> There's a combinator parsing tutorial here:
>>
>> http://www.artima.com/pins1ed/combinator-parsing.html
>
> Thanks, I have the 2nd ed of the book which I assume is very similar.
> However that's not really what I am looking for.  The book is explaining the
> principles behind how the scala parser framework works,  it isn't library
> documentation.  That's not a criticism, explaining how things work is
> exactly what the book should be doing, the problem is that the lbrary
> documentation often doesn't exist. For example listing 31.1 in the link
> above shows how to write a JSON parser based on JavaTokenParsers, yet
> there's a scala.util.parsing.json.JSON object in the library that does it
> all for you - in practice you'd just use that.  In that particular case
> there is overview documentation, but in most of the other cases there isn't.
>
Is this the kind of thing you'd prefer to see in general?

http://www.scalatest.org/scaladoc-1.6.1/#org.scalatest.FreeSpec

One concern I have had about the extent to which I have documented
ScalaTest in its Scaladocs is that there's too much tutorial in there.
You have to scroll quite a ways to get to the bottom where you can
look at the method documentation. I've never had a complaint about
that, but I'm curious if you think it is too much or just right.
Hopefully you don't think it's too little.

I also have wanted a way to create a package comment without creating
a package object. When you define a package object you get all the
public methods of AnyRef in scope at the package level, and that's not
something I want to add just to get a doc comment. But if I am
creating a package object anyway, I do put a comment on there.
ScalaTest has a package comment because I created a package object for
the ScalaTest shell:

http://www.scalatest.org/scaladoc-1.6.1/#org.scalatest.package

That doesn't say too much, because at some point I think people will
want to be looking at a user guide or getting started kind of
documentation, which I think doesn't belong in the Scaladoc.

Bill
----
Bill Venners
Artima, Inc.
http://www.artima.com

I'm attempting to draft up an outline of what is under
scala.util.parsing, and I've been looking at the stuff under
scala.util.parsing.ast which is full of warnings about experimental
code and TODO blocks. I also can't find any references to it
elsewhere, can I assume it is incomplete and can be ignored?

As an aside, the 'Use' and 'Tree' features of Javadoc would be really
useful when chasing around the hierarchies, was there a reason why
scaladoc didn't provide something similar?

2011/10/1 Alan Burlison :
> Is it just me that finds the contents of scala.util.parsing.* namespace a
> bit of a mess?  For example, what is the difference between
> StandardTokenParsers, StdTokenParsers and TokenParsers?  OK, let's look at
> the documentation:

Hi Alan, this might help:

* www.cs.kuleuven.ac.be/publicaties/rapporten/cw/CW491.pdf
* lamp.epfl.ch/teaching/foundations_of.../combinator_parsing.pdf

just do a search for "TokenParsers" in both files and some
explanations will come up.

On 10/02/11 18:13, Carlos López Camey wrote:

> Hi Alan, this might help:
>
> * www.cs.kuleuven.ac.be/publicaties/rapporten/cw/CW491.pdf
> * lamp.epfl.ch/teaching/foundations_of.../combinator_parsing.pdf

The full URL for the 2nd link is
http://lamp.epfl.ch/teaching/foundations_of_software/docs/combinator_par...
I believe

> just do a search for "TokenParsers" in both files and some
> explanations will come up.

The 2nd link is a chapter from the Programming in Scala book I believe,
which I already have. I hadn't seen the first link before though, thanks!

On Sun, Oct 2, 2011 at 02:21, Ken McDonald wrote:
>
>
> On Saturday, October 1, 2011 9:18:09 AM UTC-5, Daniel Sobral wrote:
>>
>> > Docs folks, please, please, please work on the overviews first.
>>
>> We have nothing to attach overviews to: Scaladoc ignores comments on
>> pure packages. Even the "landing page" of Scaladoc was created by
>> providing an external flag reading from an alternative file.
>
> It's been a while (before the current version of Scaladoc), but at one time
> you could document package objects and have that show up in the HTML. So I
> would just put in an empty package object into its own file, and attach all
> the overview doco to that. The biggest problem with this was simply knowing
> where to click in the HTML to access the documentation.

Yes, that works, but I won't litter the library with empty package
objects for the sake of hanging documentation. That's just wrong. On
Scalathon I even considered doing that for Regex, but I was so
disgusted by the idea that I went to, of all people, paulp and asked
what he thought about it. That surely was my subconscious at work,
because he couldn't have answered in any other way than he did! So I
ditched the idea, and slept at peace with myself that night.

On Sun, Oct 2, 2011 at 13:57, Alan Burlison wrote:
> I'm attempting to draft up an outline of what is under
> scala.util.parsing, and I've been looking at the stuff under
> scala.util.parsing.ast which is full of warnings about experimental
> code and TODO blocks.  I also can't find any references to it
> elsewhere, can I assume it is incomplete and can be ignored?

Note really. One thing that helps sometimes is grepping compiler and
library sources for stuff that seems kind of abandoned. It's been my
experience that they often are used there.

Identifying things that are truly broken or incomplete and are *not*
used by the library is useful to find things that need to be
deprecated and removed from the library altogether. There's *cruft* in
there, and keeping things that have developed code rot is not
desirable.

> As an aside, the 'Use' and 'Tree' features of Javadoc would be really
> useful when chasing around  the hierarchies, was there a reason why
> scaladoc didn't provide something similar?

Use? Tree? Can you give me an example of where I can find such things
in the Java API doc?

On 10/02/11 23:50, Daniel Sobral wrote:

> Note really. One thing that helps sometimes is grepping compiler and
> library sources for stuff that seems kind of abandoned. It's been my
> experience that they often are used there.

Well I certainly can't find any uses of the ast stuff in the rest of the
parser sources. *Are* they used anywhere?

> Identifying things that are truly broken or incomplete and are *not*
> used by the library is useful to find things that need to be
> deprecated and removed from the library altogether. There's *cruft* in
> there, and keeping things that have developed code rot is not
> desirable.

Looking at the source leads me to think the ast stuff is incomplete...

>> As an aside, the 'Use' and 'Tree' features of Javadoc would be really
>> useful when chasing around the hierarchies, was there a reason why
>> scaladoc didn't provide something similar?
>
> Use? Tree? Can you give me an example of where I can find such things
> in the Java API doc?

At the top and bottom of any class's page, e.g.

http://download.oracle.com/javase/6/docs/api/java/util/package-tree.html
http://download.oracle.com/javase/6/docs/api/java/util/class-use/ArrayLi...

> It's been a while (before the current version of Scaladoc), but at one time
> you could document package objects and have that show up in the HTML. So I
> would just put in an empty package object into its own file, and attach all
> the overview doco to that. The biggest problem with this was simply knowing
> where to click in the HTML to access the documentation.

Yes, that works, but I won't litter the library with empty package
objects for the sake of hanging documentation. That's just wrong. On
Scalathon I even considered doing that for Regex, but I was so
disgusted by the idea that I went to, of all people, paulp and asked
what he thought about it. That surely was my subconscious at work,
because he couldn't have answered in any other way than he did! So I
ditched the idea, and slept at peace with myself that night.

--
Daniel C. Sobral

I travel to the future all the time.

Would you prefer to have a package that nobody uses because the docs are inadequate? This may not be the ideal way of doing it, but it is _a_ way of doing package-level docs, and if that's the documentation that's necessary for people to understand the library, it strikes me as a reasonable choice.
Ken 

On 03/10/2011 00:45, Daniel Sobral wrote:
> Yes, that works, but I won't litter the library with empty package
> objects for the sake of hanging documentation. That's just wrong.

I am not too shocked by the idea... Unless it results in useless or bad fat bytecode...
If you see documentation as first class citizen of a library, the idea might even be quite
logical.
Now, if you state explicitly why this is so disturbing for you, I can change my mind... :-)

On Mon, Oct 3, 2011 at 00:34, Ken McDonald wrote:
>>
>> > It's been a while (before the current version of Scaladoc), but at one
>> > time
>> > you could document package objects and have that show up in the HTML. So
>> > I
>> > would just put in an empty package object into its own file, and attach
>> > all
>> > the overview doco to that. The biggest problem with this was simply
>> > knowing
>> > where to click in the HTML to access the documentation.
>>
>> Yes, that works, but I won't litter the library with empty package
>> objects for the sake of hanging documentation. That's just wrong. On
>> Scalathon I even considered doing that for Regex, but I was so
>> disgusted by the idea that I went to, of all people, paulp and asked
>> what he thought about it. That surely was my subconscious at work,
>> because he couldn't have answered in any other way than he did! So I
>> ditched the idea, and slept at peace with myself that night.
>>
>> --
>> Daniel C. Sobral
>>
>> I travel to the future all the time.
>
> Would you prefer to have a package that nobody uses because the docs are
> inadequate? This may not be the ideal way of doing it, but it is _a_ way of
> doing package-level docs, and if that's the documentation that's necessary
> for people to understand the library, it strikes me as a reasonable choice.

No, I prefer the scaladoc tool to grow up a better way of doing it.
Turning the packages into package objects have runtime consequences,
which we'll have to *live with* even after a better solution comes up,
just to keep compatibility.

On Mon, Oct 3, 2011 at 05:31, Philippe Lhoste wrote:
> On 03/10/2011 00:45, Daniel Sobral wrote:
>>
>> Yes, that works, but I won't litter the library with empty package
>> objects for the sake of hanging documentation. That's just wrong.
>
> I am not too shocked by the idea... Unless it results in useless or bad fat
> bytecode...
> If you see documentation as first class citizen of a library, the idea might
> even be quite logical.
> Now, if you state explicitly why this is so disturbing for you, I can change
> my mind... :-)

Try this: create an new directory and place a file called PO.scala in
it, with the contents below. Then compile that file and see what
results.

package object po {}

On Monday, October 3, 2011 11:10:01 AM UTC-5, Daniel Sobral wrote:

> Now, if you state explicitly why this is so disturbing for you, I can change
> my mind... :-)

Try this: create an new directory and place a file called PO.scala in
it, with the contents below. Then compile that file and see what
results.

package object po {}

--
Daniel C. Sobral

Well, I won't be doing Scala today, would it be possible to get a two-line summary of the negative consequences?
Thanks,Ken 

I travel to the future all the time.

On Mon, Oct 3, 2011 at 12:10 PM, Daniel Sobral <dcsobral@gmail.com> wrote:

On Mon, Oct 3, 2011 at 05:31, Philippe Lhoste <PhiLho@gmx.net> wrote:
> On 03/10/2011 00:45, Daniel Sobral wrote:
>>
>> Yes, that works, but I won't litter the library with empty package
>> objects for the sake of hanging documentation. That's just wrong.
>
> I am not too shocked by the idea... Unless it results in useless or bad fat
> bytecode...
> If you see documentation as first class citizen of a library, the idea might
> even be quite logical.
> Now, if you state explicitly why this is so disturbing for you, I can change
> my mind... :-)

Try this: create an new directory and place a file called PO.scala in
it, with the contents below. Then compile that file and see what
results.

package object po {}

You get two tiny dummy objects in the directory po that don't conflict with anything.  I would have thought that the "there isn't anything here" corner cases--and the "don't have objects in the library that effectively don't exist" principle--would have been the reasons to avoid it.

Surely one can't be concerned about so little overhead given e.g. Function2.

  --Rex

On Oct 1, 11:40 am, Daniel Sobral wrote:
> On Sat, Oct 1, 2011 at 13:03, Alan Burlison wrote:
> > On 10/01/11 15:18, Daniel Sobral wrote:

> There's one technical reason: someone has to do it. Well, maybe that's
> not "technical", but that's what it comes down to.
>

The library should not exist available to the public without
documentation.

The Open Source projects I contribute to and/or help manage all have
strict rules about what is acceptable code to commit to the project (I
realize the state of much open source is horrible docs, but not all
projects!). Code without documentation is not acceptable.

IMO, Scala should start following such rules. All code should be
reviewed anyway, and it should not pass review and become part of a
complete official release until documented.

In addition to thorough unit tests, I find that writing documentation
of code before it is released sometimes _significantly_ improves the
code, because it is often easier to clean up an API or remove corner
cases than it is to describe in the documentation such needless
complexities.

> A lot has been done, on the technical front, to make it easier for the
> community help with this, but most of it has not produced the expected
> results. The best effort so has is the Scala DocSpree, which took
> place one day before Scalathon this year, and was so successful that
> there is now the Monthly Scala Docspree
> (https://wiki.scala-lang.org/display/SW/Monthly+Scala+Docspree). The
> next Docspree will take place October 15th, and everyone's invited.
> All you have to do is reserve a little time anytime that Saturday,
> write or improve docs for something, and submit it. For more
> information, see the link.
>

That may be useful to catch up on old stuff that should have had docs
in the first place, but I hope that Scala going forward does NOT rely
on this documentation after the fact. Documentation up front has many
benefits.

>
> On the Docspree, many participants choose parts of the library they
> don't actually have experience with, and, with the help of REPL,
> source code and other sources (including people on ##scala-docspree),
> document them based on what they learn about it.
>

It is too bad that the authors of the code aren't documenting. That
process tends to improve the programming skills of the author. Others
may need to add a second pass of enhancements to the documentation or
go through a review process. I tend to enforce review of the code
documentation at the same time as the code itself.

> --
> Daniel C. Sobral
>
> I travel to the future all the time.

On Mon, Oct 3, 2011 at 17:01, ScottC wrote:
>
> The library should not exist available to the public without
> documentation.
>
> The Open Source projects I contribute to and/or help manage all have
> strict rules about what is acceptable code to commit to the project (I
> realize the state of much open source is horrible docs, but not all
> projects!).  Code without documentation is not acceptable.
>
> IMO, Scala should start following such rules.  All code should be
> reviewed anyway, and it should not pass review and become part of a
> complete official release until documented.

That may be the case, but this is the wrong forum to speak of it. This
is a users forum, and I'm speaking as a user (which is all I am,
anyway). Such discussions should take place on scala-language or
scala-internals, and before making any such suggestion it is better to
understand what are the constraints the project operates under.

On Oct 3, 1:24 pm, Daniel Sobral wrote:
> On Mon, Oct 3, 2011 at 17:01, ScottC wrote:
>
> > The library should not exist available to the public without
> > documentation.
>
> > The Open Source projects I contribute to and/or help manage all have
> > strict rules about what is acceptable code to commit to the project (I
> > realize the state of much open source is horrible docs, but not all
> > projects!).  Code without documentation is not acceptable.
>
> > IMO, Scala should start following such rules.  All code should be
> > reviewed anyway, and it should not pass review and become part of a
> > complete official release until documented.
>
> That may be the case, but this is the wrong forum to speak of it. This
> is a users forum, and I'm speaking as a user (which is all I am,
> anyway). Such discussions should take place on scala-language or
> scala-internals, and before making any such suggestion it is better to
> understand what are the constraints the project operates under.
>

Off topic:

I apologize if this is the wrong forum for the comment. Documentation
is a genuine user frustration, one of a few that is making it hard for
me to convince others that Scala is a viable language to introduce
beyond toy projects.
It is not a demand and I'm not expecting feedback. I used strong
wording because its what I believe, but that is only my opinion and
I'm merely a user.

> --
> Daniel C. Sobral
>
> I travel to the future all the time.

On Mon, Oct 3, 2011 at 17:56, ScottC wrote:
> On Oct 3, 1:24 pm, Daniel Sobral wrote:
>> On Mon, Oct 3, 2011 at 17:01, ScottC wrote:
>>
>> > The library should not exist available to the public without
>> > documentation.
>>
>> > The Open Source projects I contribute to and/or help manage all have
>> > strict rules about what is acceptable code to commit to the project (I
>> > realize the state of much open source is horrible docs, but not all
>> > projects!).  Code without documentation is not acceptable.
>>
>> > IMO, Scala should start following such rules.  All code should be
>> > reviewed anyway, and it should not pass review and become part of a
>> > complete official release until documented.
>>
>> That may be the case, but this is the wrong forum to speak of it. This
>> is a users forum, and I'm speaking as a user (which is all I am,
>> anyway). Such discussions should take place on scala-language or
>> scala-internals, and before making any such suggestion it is better to
>> understand what are the constraints the project operates under.
>>
>
> Off topic:
>
> I apologize if this is the wrong forum for the comment.  Documentation
> is a genuine user frustration, one of a few that is making it hard for
> me to convince others that Scala is a viable language to introduce
> beyond toy projects.
> It is not a demand and I'm not expecting feedback.  I used strong
> wording because its what I believe, but that is only my opinion and
> I'm merely a user.

I'm not criticizing the comment, just the venue. And, at that, I only
do it because, as a user, and one who does care a lot about
documentation (see my previously mentioned efforts in this area), I'm
interested in having such comments result in actual improvements on
the situation. The only two ways I know of to do that is to get more
people to volunteer to help with it, and to get the message to other
people who can take action in other ways to improve it, and,
preferably, prepared to make their case in a way that won't get them
dismissed.