2.11.x collection documentation fixes by janekdb · Pull Request #4760 · scala/scala

janekdb · 2015-09-21T20:36:50Z

This PR started life as #4651.

The bulk of it was separated out into more focused PRs,
#4765 - ScalaDoc comparison script
#4789 - Parameter and type renaming
#4803 - tparam naming consistency

Original PR comment

Some doc fixes for GenTraversableOnce, methods from aggregate to foreach in alphabetical order.

This covers a-f so far. The rest of the alphabet is pending.

Types of corrections:

 * Rewordings, (hopefully) better explanations
 * Fixing type params and parameter names so doc gets inherited properly
 * Adjusting REPL output to what I get with 2.11
 * Moving documentation up to GenTraversableOnce (e.g. copyToArray
   was defined in GTO, but had no documentation there, only in TraversableLike)
 * Squashing some horizontal whitespace

TODO

Confirm build green and spot check changes
Take off on-hold

DONE

1️⃣ This was temporarily added to get past a git rebase --continue problem.

Align parameters names to use p for predicates and op for combining operations. Based on scala#4760. Extended to include, - Tuple2Zipped - Tuple3Zipped - Either The original author was vsalvis.

janekdb · 2015-10-14T18:55:43Z

src/library/scala/collection/GenTraversableOnce.scala

Prefer satisfies phrasing.

I also still prefer satisfies

janekdb · 2015-10-15T19:08:45Z

src/library/scala/collection/GenTraversableLike.scala

Question about applying this change to two other traits.

TraversableLike could also have this method and documentation deleted. It would inherit the method indirectly from GenTraversableOnce.

TraversableOnce also inherits foreach from GenTraversableOnce so it could be deleted as well.

Would this be safe to do?

We're trying to simplify the collections, which may mean that the whole Gen hierarchy goes away (since it is generalizing over serial vs. parallel collections). To prevent extra future work, I wouldn't remove anything from X just because it also is found in GenX.

I will restrict the change to removing the duplicated documentation in TraversableLike.

Ichoran · 2015-10-15T19:52:42Z

src/library/scala/collection/GenTraversableOnce.scala

Starting a paragraph with "So" is somewhat inelegant.

Ichoran · 2015-10-15T19:58:02Z

src/library/scala/collection/TraversableLike.scala

From where will these docs come if they're deleted here?

The documentation from GenTraversableOnce is used. I have confirmed this by building the docs after adding a some unique text to GenTraversableOnce to be sure of the source.

janekdb · 2015-10-19T19:48:38Z

/rebuild

janekdb · 2015-10-23T21:04:26Z

src/library/scala/collection/package.scala

Mention JavaConverters.

SethTisue · 2015-10-27T12:44:59Z

@janekdb #4803 is merged now

janekdb · 2015-10-27T12:49:16Z

Thanks.

- Remove some duplicate method documentation that is now inherited - Whitespace edits - Rewording of method docs - Clearer usage examples - tparam alignment for some usecase tags - Prefer () to { } for do nothing bodies

janekdb · 2015-10-27T17:43:32Z

@SethTisue - please take off on-hold.

Review by @heathermiller , @dickwall , @som-snytt , @Ichoran .

dickwall · 2015-11-02T22:52:15Z

LGTM - there are a lot of changes here but I spot no mistakes. Will wait for at least one more LGTM (double check) on this latest round of changes before merging. Ping @heathermiller, @som-snytt or @Ichoran

adriaanm · 2015-11-10T00:30:37Z

@Ichoran, could you take another look?

soc · 2015-11-12T11:55:49Z

Not @Ichoran, but LGTM.

adriaanm · 2015-11-12T19:48:52Z

Thanks!

…-fixes-previously-4651 2.11.x collection documentation fixes

janekdb mentioned this pull request Sep 21, 2015

Collection documentation fixes #4651

Closed

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from 5cb72a5 to edf72b8 Compare September 21, 2015 21:00

SethTisue added the on-hold label Sep 22, 2015

janekdb mentioned this pull request Sep 23, 2015

Script to compare the current scaladoc with the parent commit's doc #4765

Merged

17 tasks

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from c9762dc to efc7465 Compare September 23, 2015 21:25

SethTisue added this to the 2.11.8 milestone Sep 24, 2015

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch 2 times, most recently from c9dbf06 to 95aa214 Compare October 5, 2015 10:45

janekdb changed the title ~~2.11.x collection documentation fixes (previously pr 4651)~~ 2.11.x collection documentation fixes Oct 5, 2015

janekdb mentioned this pull request Oct 6, 2015

Rename forall, exists and find predicate and operator params. #4789

Merged

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch 4 times, most recently from e61f646 to 34237a6 Compare October 14, 2015 18:51

janekdb reviewed Oct 14, 2015
View reviewed changes

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from 34237a6 to c4a3d9e Compare October 14, 2015 19:10

janekdb reviewed Oct 15, 2015
View reviewed changes

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from c4a3d9e to e467b75 Compare October 15, 2015 19:41

Ichoran reviewed Oct 15, 2015
View reviewed changes

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from e467b75 to 9891468 Compare October 15, 2015 19:57

Ichoran reviewed Oct 15, 2015
View reviewed changes

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch 3 times, most recently from 0f5332e to 93dd8a6 Compare October 16, 2015 10:25

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from 15f972d to f6d5752 Compare October 18, 2015 19:09

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch 6 times, most recently from 2652b0e to 63afdd6 Compare October 23, 2015 20:48

janekdb reviewed Oct 23, 2015
View reviewed changes

src/library/scala/collection/package.scala Outdated

Copy link

Member Author

janekdb Oct 23, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mention JavaConverters.

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from 63afdd6 to e818e52 Compare October 23, 2015 21:50

janekdb mentioned this pull request Oct 23, 2015

Conform foreach tparam to majority naming convention #4803

Merged

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from e818e52 to 4830d4d Compare October 27, 2015 13:54

Improve collections documentation and prefer () to {}

e3cbcd5

- Remove some duplicate method documentation that is now inherited - Whitespace edits - Rewording of method docs - Clearer usage examples - tparam alignment for some usecase tags - Prefer () to { } for do nothing bodies

janekdb force-pushed the 2.11.x-collection-documentation-fixes-previously-4651 branch from 4830d4d to e3cbcd5 Compare October 27, 2015 13:56

scala-jenkins added the reviewed label Oct 27, 2015

SethTisue removed on-hold labels Oct 27, 2015

scala-jenkins added the reviewed label Oct 27, 2015

SethTisue removed the reviewed label Oct 27, 2015

scala-jenkins added the reviewed label Nov 2, 2015

adriaanm added a commit that referenced this pull request Nov 12, 2015

Merge pull request #4760 from janekdb/2.11.x-collection-documentation…

2218497

…-fixes-previously-4651 2.11.x collection documentation fixes

adriaanm merged commit 2218497 into scala:2.11.x Nov 12, 2015

Conversation

janekdb commented Sep 21, 2015

TODO

DONE

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janekdb commented Oct 19, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SethTisue commented Oct 27, 2015

Uh oh!

janekdb commented Oct 27, 2015

Uh oh!

janekdb commented Oct 27, 2015

Uh oh!

dickwall commented Nov 2, 2015

Uh oh!

adriaanm commented Nov 10, 2015

Uh oh!

soc commented Nov 12, 2015

Uh oh!

adriaanm commented Nov 12, 2015

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants