docs.scala-lang icon indicating copy to clipboard operation
docs.scala-lang copied to clipboard

Published 20 hours ago • verified publisher icon scala

Update code examples to show both Scala 2 and Scala 3 syntax

Open julienrf opened this issue 3 years ago • 2 comments

We would like to have a single website documenting both Scala 2 and Scala 3 since, in most of the cases, their syntax is very similar, and their features are almost all the same. However, there can still be some syntactic differences between idiomatic Scala 2 code and idiomatic Scala 3 code. Therefore, we want to display both styles in our code examples by using tabs:

Screenshot 2022-07-27 at 14-37-55 Futures and Promises

For code examples that are idiomatic in both Scala 2 and Scala 3, we show a single tab labelled “Scala 2 and 3”:

Screenshot from 2022-07-27 14-39-09

Unfortunately, there are lots of code examples in the documentation, and updating all of them is a huge (and repetitive) task for one person. But if a few dozen members of the community were each updating a couple of pages, the job would be done very quickly. So, everyone is welcome to help!

The policy for updating code examples is the following: show the most idiomatic style for all the code examples, for Scala 2 and Scala 3. For Scala 3 code examples, this means using the new control syntax, the indentation-significant syntax, using and given, @main, .* wildcard import, ? wildcard type argument, tuple indexed access, etc.

You can find the instructions to write tabbed code examples in the documentation.

Here is the list of pages that need to be updated. If you are interested in contributing, please add a comment to announce that you start working on a page, and I will mark it “in progress” to prevent overlapping contributions:

  • [x] Tour of Scala (source files are in the _tour/ directory)
    • [x] ~Basics~ #2458
    • [x] ~Unified Types~ #2492
    • [x] ~Classes~ #2474
    • [x] ~Default Parameter Values~ #2493
    • [x] ~Named Arguments~ #2521
    • [x] ~Traits~ #2455
    • [x] ~Tuples~ #2476
    • [x] ~Class Composition with Mixins~ #2524
    • [x] ~Higher-order Functions~ #2525
    • [x] ~Nested Methods~ #2528
    • [x] ~Multiple Parameter Lists (Currying)~ #2530
    • [x] ~Case Classes~ https://github.com/scala/docs.scala-lang/pull/2533
    • [x] ~Pattern Matching~ #2461
    • [x] ~Singleton Objects~ #2497
    • [x] ~Regular Expression Patterns~ #2534
    • [x] ~Extractor Objects~ #2535
    • [x] ~For Comprehensions~ #2494
    • [x] ~Generic Classes~ #2537
    • [x] ~Variances~ #2547
    • [x] ~Upper Type Bounds~ #2548
    • [x] ~Lower Type Bounds~ #2549
    • [x] ~Inner Classes~ #2550
    • [x] ~Abstract Type Members~ #2551
    • [x] ~Compound Types~ #2552
    • [x] ~Self-type~ #2553
    • [x] ~Implicit Parameters~ #2496
    • [x] ~Implicit Conversions~ #2630
    • [x] ~Polymorphic Methods~ #2554
    • [x] ~Type Inference~ #2557
    • [x] ~Operators~ #2561
    • [x] ~By-name Parameters~ #2564
    • [x] ~Annotations~ #2566
    • [x] ~Packages and Imports~ #2570
    • [x] ~Package Objects~ #2579
  • [x] Guides and Overviews (source files are in the _overviews/ directory)
    • [x] Scala Collections
      • [x] ~Introduction~ https://github.com/scala/docs.scala-lang/pull/2571
      • [x] ~Mutable and Immutable Collections~ https://github.com/scala/docs.scala-lang/pull/2571
      • [x] ~Trait Iterable~ https://github.com/scala/docs.scala-lang/pull/2571
      • [x] ~The sequence traits Seq, IndexedSeq, and LinearSeq~ https://github.com/scala/docs.scala-lang/pull/2571
      • [x] ~Sets~ https://github.com/scala/docs.scala-lang/pull/2572
      • [x] ~Maps~ #2455
      • [x] ~Concrete Immutable Collection Classes~ https://github.com/scala/docs.scala-lang/pull/2572
      • [x] ~Concrete Mutable Collection Classes~ https://github.com/scala/docs.scala-lang/pull/2572
      • [x] ~Arrays~ https://github.com/scala/docs.scala-lang/pull/2574
      • [x] ~Strings~ https://github.com/scala/docs.scala-lang/pull/2574
      • [x] ~Performance Characteristics~ (no code examples)
      • [x] ~Equality~ https://github.com/scala/docs.scala-lang/pull/2574
      • [x] ~Views~ https://github.com/scala/docs.scala-lang/pull/2574
      • [x] ~Iterators~ https://github.com/scala/docs.scala-lang/pull/2575
      • [x] ~Creating Collections From Scratch~ https://github.com/scala/docs.scala-lang/pull/2575
      • [x] ~Conversions Between Java and Scala Collections~ https://github.com/scala/docs.scala-lang/pull/2575
    • [x] ~The Architecture of Scala Collections~ https://github.com/scala/docs.scala-lang/pull/2576#pullrequestreview-1129904740
    • [x] ~Implementing Custom Collections~ #2585
    • [x] ~Adding Custom Collection Operations~ #2589
    • [x] Migration from Scala 2 to Scala 3
      • [x] ~Migration Tutorial~ #2597
      • [x] ~Scala 3 Syntax Rewriting~ #2643
      • [x] Incompatibility Table
        • [x] ~Syntactic Changes~ #2722
        • [x] ~Dropped Features~ #2723
        • [x] ~Contextual Abstractions~ #2724
        • [x] ~Other Changed Features~ #2725
        • [x] ~Type Checker~ #2726
        • [x] Type Inference
      • [x] Compiler Plugins
        • [x] Kind Projector Migration
    • [x] ~Scala 3 Macros~ (marked as scala 3 only)
    • [x] ~Value Classes and Universal Traits~ #2863
    • [x] ~An Overview of TASTy~ #2768
    • [x] ~String Interpolation~ #2455
    • [x] ~Implicit Classes~ #2787
    • [x] ~Library Author Guide~ #2873
    • [x] ~Futures and Promises~ #2467
    • [x] ~Optimizer~ (marked as scala 2 only)
  • [ ] Scala 3 Book (source files are in the _overviews/scala3-book directory)
    • [x] ~Scala 3 Features~ #2495
    • [x] ~Why Scala 3?~ #2510
    • [x] A Taste of Scala
      • [x] ~Hello, World!~ #2450
      • [x] ~The REPL~ #2487
      • [x] ~Variables and Data Types~ #2568
      • [x] ~Control Structures~ #2580
      • [x] ~Domain Modeling~ #2581
      • [x] ~Methods~ #2582
      • [x] ~First-Class Functions~ #2583
      • [x] ~Singleton Objects~ #2584
      • [x] ~Collections~ #2586
      • [x] ~Contextual Abstractions~ #2587
      • [x] ~Top-level Definitions~ #2588
    • [x] ~A First Look at Types~ #2511
    • [x] ~Control Structures~ #2461
    • [x] ~Domain Modeling~ (no code)
      • [x] ~Tools~ #2590
      • [x] ~OOP Modeling~ #2591
      • [x] ~FP Modeling~ #2592
    • [x] ~Methods~ (no code)
      • [x] ~Method Features~ #2594
      • [x] ~main Methods~ #2609
    • [x] Functions (no code)
      • [x] ~Anonymous Functions~ #2602
      • [x] ~Function Variables~ #2623
      • [x] ~Eta Expansion~ #2644
      • [x] ~Higher-Order Functions~ #2598
      • [x] ~Write Your Own map Method~ #2625
      • [x] ~Creating a Method That Returns a Function~ #2664
    • [x] ~Packaging and Imports~ #2745
    • [x] ~Scala Collections~ #2614
      • [x] ~Collections Types~ #2614
      • [x] ~Collections Methods~ #2614
    • [x] ~Functional Programming~ #2617
      • [x] ~What is Functional Programming~ (no code)
      • [x] ~Immutable Values~ #2617
      • [x] ~Pure Functions~ #2617
      • [x] ~Functions Are Values~ #2617
      • [x] ~Functional Error Handling~ #2617
    • [x] ~Types and the Type System~ #2599
      • [x] ~Inferred Types~ #2599
      • [x] ~Generics~ #2599
      • [x] ~Intersection Types~ #2653
      • [x] ~Union Types~ #2768
      • [x] ~Algebraic Data Types~ #2768
      • [x] ~Variance~ #2756
      • [x] ~Opaque Types~ #2863
      • [x] ~Structural Types~ #2864
      • [x] ~Dependent Function Types~ #2865
      • [x] ~Other Types~ #2865
    • [x] ~Contextual Abstractions~
      • [x] ~Given Instances and Using Clauses~ #2640
      • [x] ~Type Classes~ #2787
      • [x] ~Context Bounds~ #2689
      • [x] ~Given Imports~ #2689
      • [x] ~Extension Methods~ #2787
      • [x] ~Multiversal Equality~ #2689
      • [x] ~Implicit Conversions~ #2787
    • [ ] Concurrency
    • [ ] Scala Tools
      • [ ] Building and Testing Scala Projects with sbt
      • [ ] Worksheets
    • [x] ~Interacting with Java~ #2867
    • [ ] Scala for Java Developers
    • [ ] Scala for JavaScript Developers
    • [ ] Scala for Python Developers
  • [ ] Tutorials (source files are in the _overviews/tutorials directory or _getting-started/)
    • [x] ~Getting started with Scala and sbt on the command line~ #2475
    • [x] ~Getting started with Scala in IntelliJ~ #2454
    • [x] ~Scala for Java Programmers~ #2499
    • [ ] Scala on Android
    • [ ] Scala with Maven

Note: in some cases, not only the code examples need to be updated, but also the text in the documentation (e.g. @main methods, extension methods, contextual abstractions, enums). In that case, the task is more complicated. Feel free to ask for help on the #scala-contributors channel of the Scala discord server, or consider switching to a simpler page.

julienrf avatar Jul 27 '22 13:07 julienrf

I tried to update "Named Arguments". I'm waiting for feedback before trying update on other page.

As my update is now merged via #2521 (thanks bishabosha), I propose to update a next page: "Toor / Class Composition with Mixins"

flomebul avatar Sep 12 '22 16:09 flomebul

I leave a note here to say that https://docs.scala-lang.org/contribute/add-guides.html#scala-2-vs-scala-3 should be updated to explain the following points

  • [ ] single tab for Scala 3 should read "Scala 3 Only"
  • [ ] single tab for Scala 2 should read "Scala 2 Only"
  • [ ] Scala 3 code tabs should not have ```scala mdoc in the code fence

bishabosha avatar Sep 15 '22 08:09 bishabosha