Possible documentation improvements

[MateuszKubuszok]

This ticket is intended to be a pinned list of things that we can improve in the documentation. They might become full issues, they might be done as a part of another PR, they might be a good candidates for a contribution!

Latest stable documentation can be found at https://chimney.readthedocs.io/en/stable/ , latest master build can be found at https://chimney.readthedocs.io/en/latest/. Rendering it locally is described in CONTRIBUTION.md.

Things to improve

• some mini tutorial

  • simple user case with success - done in Improve the docs a bit #615
  • what happens on error - done in Improve the docs a bit #615
  • how to use the feedback to fix it - done in Improve the docs a bit #615 but can be improved(?)
  • same for partials
  • and patchers

• add mention to automatic vs semiautomatic derivation that Chimney DOES NOT implement it in the same way as e.g. Circe so all the typical advises ("ban auto, semiauto only") does not apply - one in Improve the docs a bit #615,

  • ideally provide a link to the presentation once I do it and video will be available (done in Add link to sanely-automatic derivation #651)

• add mention (and tests) that .enableBeanSetters also enable writing to vars - it's an unintended side-effect of:

  • the fact that @BeanProperty on Scala 3 would generate name_= symbol in tasty, while createding setName in JVM bytecode
  • the fact that Scala 2.13 can read case classes compiled with Scala 3
  • our goal that, ideally, the behavior should be the same on all versions of Scala

  meaning that vars have to be treated the same way as bean setters - done in Ensure with tests and document the alignment of vars and setters #621

• add example of the above showing that one can convert between normal case class and js.Object with defined vars - e.g. https://scastie.scala-lang.org/I7yzzeRQT6yWDoFjXQHoCA - done in Ensure with tests and document the alignment of vars and setters #621

• explanation for optics-like uses cases - while we mentioned in Goals and non-goals that Chimney is NOT a lens library, with changes that happened over the last few versions (particularly around 1.0.0) it can be used to cover some cases that are typically within the lens domain - done in Better lens-like operations support #583

• more good examples of Cats' integrations:

  • mapN/parMapN usage of Transformer/PartialTransformer/partial.Result - done in Expand cookbook docs #657
  • andThen/combine usage of Transformer/PartialTransformer/Codec/Iso - done in Expand cookbook docs #657
  • conversions to/from Chain/NonEmptyChain/NonEmptyList/NonEmptyVector/NonEmptySet... - done in Expand cookbook docs #657

• more good examples of Protobuf integrations:

  • example of .enableNonAnyValWrappers required to handle oneof value wrappers (single-element case classes storing sealed hierarchy) - done in More sources in docs, missing PB example #585

• adding comparisons with other popular mapping libraries ("Coming from ..." sections in the documentation #350) and keeping existing ones up to date

• some section listing all flags/overrides in one place with links to their explanation - done as a part of Provide Scala-version-agnostic way of reading macro settings #572

• some section explaining integrations package and AsResult type class - done in Make integrations a separate section in cookbook #584

• links to other tutorials - done in More sources in docs, missing PB example #585

  • https://www.youtube.com/watch?v=SNc7xeHrKnQ + https://mateuszkubuszok.github.io/DomainApiDtoChimney (newest example with Chimeny)
  • https://mateuszkubuszok.github.io/ChimneyInternalsPresentation (Chimney under the hood examples with old macros)
  • https://softwaremill.com/5-scala-libraries-that-will-make-your-life-easier/ (includes Chimney, as # 2)
  • https://www.youtube.com/watch?v=ezz0BpEHEQY + https://youtu.be/ZymD5NuOwdA?si=P-4AnMiaIi2LVKVW
  • https://www.youtube.com/watch?v=U67BAeH3cxo

• in CONTRIBUTING.md

  • how to add OSS Sonatype snapshot repository to test - done as a part of Better singleton types support #559
  • explain the missing coverage:
    • Scala 3 ignores $COVERAGE-OFF$
    • disableX flags are called only in compileErrors, so scoverage does not catch it
    • we were not using all of apply/unapply in type constructor although it's convenient to have them always available
    • some could be fixed OR ignores though

• last but not least: typos, erroneously put markdown tags, grammar fixes are always welcome!