Uploaded image for project: 'Scala Programming Language'
  1. Scala Programming Language
  2. SI-8904

Inconsistent DocDef nodes visibility at macro expansion time

    Details

    • Type: Bug
    • Status: Open
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: Scala 2.11.0, Scala 2.11.1, Scala 2.11.2
    • Fix Version/s: None
    • Component/s: Macros, Reflection
    • Labels:
      None

      Description

      I'm contributing to the MacWire project which leverages scala macros to perform compile-time dependency injection.

      Few days ago we encountered a problem - I'm not sure if my problem is a kind of compiler bug or some undocumented but intentional behaviour.

      Consider following code snippet:

      package com.example
       
      trait SomeTrait {
       
        /**
        * some comment what this service does.
        */
        lazy val someService: Service = MyService
       
      }

      While running 'sbt compile', above code produces the following syntax tree:

      ClassDef(
        Modifiers(ABSTRACT | DEFAULTPARAM / TRAIT),
        com.example.SomeTrait,
        List(),
        Template(
          List(
            Select(Ident(scala), TypeName("AnyRef"))
          ),
          noSelfType,
          List(
            DefDef(Modifiers(), TermName("$init$"), List(), List(List()), TypeTree(), Block(List(), Literal(Constant(())))),
            ValDef(Modifiers(LAZY), TermName("service "), Ident(com.example.Service), Ident(com.example.MyService))
          )
        )
      )

      and 'sbt doc' results in:

      ClassDef(
        Modifiers(ABSTRACT | DEFAULTPARAM / TRAIT),
        com.example.SomeTrait,
        List(),
        Template(
          List(
            Select(Ident(scala), TypeName("AnyRef"))
          ),
          noSelfType,
          List(
            DefDef(Modifiers(), TermName("$init$"), List(), List(List()), TypeTree(), Block(List(), Literal(Constant(())))),
            DocDef(
              DocComment(
                /**
                * some comment what this service does.
                */,
                RangePosition(..), NoPosition()
              ),
              ValDef(Modifiers(LAZY), TermName("service "), Ident(com.example.Service), Ident(com.example.MyService))
            )
          )
        )
      )

      The difference is in Template bodies - in the latter case ValDef is wrapped within DocDef node.

      AFAIK DocDefs should be removed (flattened) by analizer, according to comment in source code https://github.com/scala/scala/blob/2.11.x/src/compiler/scala/tools/nsc/ast/Trees.scala#L24.

      Even if presence of DocDefs at 'doc' task isn't a bug (I'm only guessing that macro expansion is done after scaladoc generation, in later compiler phase. Or maybe DocDefs are necessary here to generate doc?), then I think that inconsistency between ASTs may be an issue.

      I found, that @retronym solved similar problem with constructors hidden by DocDef node: https://github.com/scala/scala/commit/c4561c1d4945a38febc41436ed333569d0e9a063

      Unfortunately, we can't just match against DocDef in our code (https://github.com/adamw/macwire/blob/master/macros/src/main/scala/com/softwaremill/macwire/ValuesOfTypeInEnclosingClassFinder.scala#L16-L22) because it's not present in public Trees API.
      Thus the only working workaround is to disable macro expansion at compile:doc.
      (I have an idea to try match on DocDefs using quasiquotes, but I haven't tested it yet)

      Source code for the MacWire is available here: https://github.com/adamw/macwire
      Here's an issue report, caused by described DocDef presence: https://github.com/adamw/macwire/issues/21
      And simple project, which we used to reproduce the problem: https://github.com/mkubala/macwire-bug-demonstration

      I think that DocDef should be always invisible at macro expansion time or visible, with appropriate DocDef extractor available in public API.
      IMHO anything will be better than lack of consistency.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                burmako Eugene Burmako
                Reporter:
                mkubala Marcin Kubala
              • Votes:
                1 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated: