Fix #10648: Fixes of syntax documentation #10658

odersky · 2020-12-04T17:11:15Z

Fix documentation about indentation syntax. Also fix syntax summary (globally).

The fixes omit documenting : in extension blocks. These are disabled
in a separate commit.

There are two reasons for omitted in : in extensions:

they are not needed, and there should be one way to do things
they are confusing since everywhere else a : at eol starts a
new scope, but here it doesn't.

odersky · 2020-12-04T17:16:06Z

There are now two syntax.md files, one in docs/reference, the other in docs/internal.

The file in docs/reference contains only the official 3.0 syntax and omits the column with tree node info.
The file in docs/internal contains also deprecated and experimental syntax and adds the tree node info column.

It will be a bit painful to keep the two in sync, but it's better to have amn official, stable syntacx summary in the official documentation.

b-studios

Copying the two syntax documents indeed leads to additional maintenance effort. Should we just present the diff in internals and link to the official one?

b-studios · 2020-12-07T12:39:16Z

docs/docs/internals/syntax.md

@@ -1,6 +1,6 @@
 ---
 layout: doc-page
-title: "Scala Syntax Summary"
+title: "Scala3 Syntax Summary"


Suggested change

title: "Scala3 Syntax Summary"

title: "Scala 3 Syntax Summary"

b-studios · 2020-12-07T12:40:31Z

compiler/src/dotty/tools/dotc/transform/ExtensionMethods.scala

@@ -190,7 +190,7 @@ object ExtensionMethods {
        // See the documentation of `memberSignature` to understand why `.stripPoly.ensureMethodic` is needed here.
        candidates filter (c => FullParameterization.memberSignature(c.info) == imeth.info.stripPoly.ensureMethodic.signature)
      assert(matching.nonEmpty,
-       i"""no extension method found for:
+       i"""no extension method found for


Is this an accidental change?

Well spotted. Yes, that was my regex search misfiring...

b-studios · 2020-12-07T13:04:48Z

docs/docs/reference/other-new-features/indentation.md

-RefinedType  ::=  AnnotType {[colonEol] Refinement}
+Template    ::=  InheritClauses [colonEol] [TemplateBody]
+EnumDef     ::=  id ClassConstr InheritClauses [colonEol] EnumBody
+Packaging   ::=  ‘package’ QualId [nl | colonEol] ‘{’ TopStatSeq ‘}’


Maybe I am missing something, but I cannot recognize the colonEol in the parser code for packages:

https://github.com/lampepfl/dotty/blob/44514a34943134f7072881c63502d3f773204f1b/compiler/src/dotty/tools/dotc/parsing/Parsers.scala#L3720-L3724

Is rewriteWithColon doing this?

The comment above also does not reflect the colon:

https://github.com/lampepfl/dotty/blob/44514a34943134f7072881c63502d3f773204f1b/compiler/src/dotty/tools/dotc/parsing/Parsers.scala#L3718

It's in possibleTemplateStart(). I added a test to verify that : is indeed significant.

b-studios · 2020-12-07T13:05:59Z

tests/neg/i5773.scala

@@ -23,7 +23,7 @@ object Main {
 21 |    println(1 appendS 2)
   |            ^^^^^^^^^
   |value appendS is not a member of Int.
-   |An extension method was tried, but could not be fully constructed:


Like the change in the source, is this intended?

b-studios · 2020-12-09T11:59:09Z

@odersky there are also still occurrences of : in the documentation on extension methods. I can fix those and push to this branch if you want.

odersky · 2020-12-09T12:51:49Z

@b-studios I think I got them all now. I was looking for " extension.*:$" so extensions starting in the first column slipped through.

b-studios · 2020-12-09T13:06:32Z

docs/docs/reference/contextual/extension-methods.md

@@ -103,7 +103,7 @@ a single extension and enclose all methods in braces or an indented region follo
 Example:


The text above this line would also need to be adjusted.

Well spotted. I'll update the doc.

The fixes omit documenting `:` in extension blocks. These will be disabled in a separate commit. There are two reasons for omitted in `:` in extensions: - they are not needed, and there should be one way to do things - they are confusing since everywhere else a `:` at eol starts a new scope, but here it doesn't.

- cleanup rules - drop sidebar with tree node info - put in reference directory and link with sidebar

Everytime I clean everything a new version of QuotesImpl is merged that brings back the `:`s...

japgolly · 2020-12-09T22:59:02Z

they are confusing since everywhere else a : at eol starts a new scope, but here it doesn't.

I'm trying hard to understand this reasoning but I can't make sense of it. Pretty much everywhere else we have trailing :s, what's special about extension blocks? Even the comment above that it doesn't create a new scope makes no sense to me. But.... of course it creates a new scope. Everything indented under extension is defined within that extension scope. I'm sure the back and forth much be annoying but I urge you to please reconsider this. I can't explain emphatically enough how confusing this is.

odersky linked an issue Dec 4, 2020 that may be closed by this pull request

Documentation is unclear about new brace-less syntax #10648

Closed

odersky force-pushed the fix-#10648 branch from f2c935e to 1242aca Compare December 4, 2020 17:15

odersky force-pushed the fix-#10648 branch from 1242aca to bf8a362 Compare December 4, 2020 17:17

odersky changed the title ~~Fix #10648~~ Fix #10648: Fixes of syntax documentation Dec 4, 2020

odersky requested a review from b-studios December 4, 2020 17:19

odersky force-pushed the fix-#10648 branch 3 times, most recently from 974cf5c to 44514a3 Compare December 4, 2020 21:26

odersky assigned b-studios Dec 6, 2020

b-studios reviewed Dec 7, 2020

View reviewed changes

odersky force-pushed the fix-#10648 branch 3 times, most recently from 327f7ab to 06abeb7 Compare December 9, 2020 11:54

odersky force-pushed the fix-#10648 branch from 06abeb7 to 732b92a Compare December 9, 2020 12:50

b-studios reviewed Dec 9, 2020

View reviewed changes

odersky force-pushed the fix-#10648 branch 2 times, most recently from c2d80fa to 943bf9e Compare December 9, 2020 14:29

odersky force-pushed the fix-#10648 branch from 943bf9e to 2a007db Compare December 9, 2020 15:41

odersky added 8 commits December 9, 2020 17:01

Drop colon in extension methods

ba38536

Officialize syntax

e5be3e7

- cleanup rules - drop sidebar with tree node info - put in reference directory and link with sidebar

Fix rebase breakage and update scala3doc files

f405235

Drop freshly added :s after extension

501fa36

Address review comments

2b9b5e4

Drop another : after extension

564db28

Friendlier error message when a : is given after extension clause

aef5689

Eliminate more : after extension

681d1b3

Everytime I clean everything a new version of QuotesImpl is merged that brings back the `:`s...

odersky added 2 commits December 9, 2020 17:01

Drop : after extension in docs and dokka tests

1231a71

Fix cps-async

3b45151

odersky force-pushed the fix-#10648 branch from 26a2f59 to 3b45151 Compare December 9, 2020 16:03

odersky merged commit 663d334 into scala:master Dec 9, 2020

odersky deleted the fix-#10648 branch December 9, 2020 21:20

b-studios mentioned this pull request Dec 10, 2020

Updating docs at dotty.epfl.ch #10633

Open

16 tasks

anatoliykmetyuk mentioned this pull request Dec 10, 2020

Trim stack traces in REPL #10717

Merged

Kordyjan added this to the 3.0.0 milestone Aug 2, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix #10648: Fixes of syntax documentation #10658

Fix #10648: Fixes of syntax documentation #10658

Uh oh!

odersky commented Dec 4, 2020 •

edited

Loading

Uh oh!

odersky commented Dec 4, 2020

Uh oh!

b-studios left a comment

Uh oh!

b-studios Dec 7, 2020

Uh oh!

b-studios Dec 7, 2020

Uh oh!

odersky Dec 9, 2020

Uh oh!

b-studios Dec 7, 2020

Uh oh!

odersky Dec 9, 2020

Uh oh!

b-studios Dec 7, 2020

Uh oh!

b-studios commented Dec 9, 2020

Uh oh!

odersky commented Dec 9, 2020

Uh oh!

b-studios Dec 9, 2020

Uh oh!

odersky Dec 9, 2020

Uh oh!

japgolly commented Dec 9, 2020

Uh oh!

Uh oh!

	title: "Scala3 Syntax Summary"
	title: "Scala 3 Syntax Summary"

		@@ -103,7 +103,7 @@ a single extension and enclose all methods in braces or an indented region follo
		Example:

Fix #10648: Fixes of syntax documentation #10658

Fix #10648: Fixes of syntax documentation #10658

Uh oh!

Conversation

odersky commented Dec 4, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

odersky commented Dec 4, 2020

Uh oh!

b-studios left a comment

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!

b-studios commented Dec 9, 2020

Uh oh!

odersky commented Dec 9, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

japgolly commented Dec 9, 2020

Uh oh!

Uh oh!

odersky commented Dec 4, 2020 •

edited

Loading