Scala Programming Language
  1. Scala Programming Language
  2. SI-4360

general problem with figuring out when to show a fully qualified name and when not to

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: Scala 2.10.0-M5
    • Component/s: Scaladoc Tool
    • Labels:
      None

      Description

      === What steps will reproduce the problem (please be specific and use wikiformatting)? ===

      build file with scaladoc
      
      /**
       * Subclass of <code>org.jmock.Expectations</code> that provides <code>withArg</code>
       * alternatives to the <code>with</code> methods defined in its superclass.
       *
       * <p>
       * <code>JMockCycle</code>'s <code>expecting</code> method of passes an instance of this class
       * to the function passed into <code>expectations</code>. Because <code>JMockExpectations</code>
       * extends <code>org.jmock.Expectations</code>, all of the <code>Expectations</code> methods are
       * available to be invoked on instances of this class, in addition to
       * several overloaded <code>withArg</code> methods defined in this class. These <code>withArg</code> methods simply
       * invoke corresponding <code>with</code> methods on <code>this</code>. Because <code>with</code> is
       * a keyword in Scala, to invoke these directly you must surround them in back ticks, like this:
       * </p>
       *
       * <pre>
       * oneOf (mockCollaborator).documentAdded(`with`("Document"))
       * </pre>
       *
       * <p>
       * By importing the members of the <code>JMockExpectations</code> object passed to
       * a <code>JMockCycle</code>'s <code>executing</code> method, you can
       * instead call <code>withArg</code> with no back ticks needed:
       * </p>
       *
       * <pre>
       * oneOf (mockCollaborator).documentAdded(withArg("Document"))
       * </pre>
       *
       * @author Bill Venners
       */
      
      class JMockExpectations
      
      

      === What is the expected behavior? ===

      fully qualified name:

      org.hamcrest.Matcher

      === What do you see instead? ===

      Matcher

      === Additional information ===
      (for instance, a link to a relevant mailing list discussion)

      In JMockSugar. some of the methods take a Matcher, but it just says
      Matcher. Well that's a org.hamcrest.Matcher, not a
      org.scalatest.Matcher, and there's no way to tell from the
      documentation

      === What versions of the following are you using? ===

      • Scala: Scala code runner version 2.8.1.final – Copyright 2002-2010, LAMP/EPFL
      • Java: java version "1.6.0_18"
        OpenJDK Runtime Environment (IcedTea6 1.8.7) (fedora-50.1.8.7.fc13-i386)
        OpenJDK Server VM (build 14.0-b16, mixed mode)
      • Operating system: Linux localhost.localdomain 2.6.34.8-68.fc13.i686.PAE SI-1 SMP Thu Feb 17 14:54:10 UTC 2011 i686 i686 i386 GNU/Linux

        Activity

        Hide
        Heather Miller added a comment -

        As this ticket stands, this is not reproducible. It requiers a now-dated version of ScalaTest source. I dug around for a bit in ScalaTest source and Scaladoc, and it seems that JMockSugar doesn't exist any longer, so I can't get a full idea of what's really happening at this point.

        In general, self-contained and minimized code examples are what we need to issue a fix.

        Can you please submit a self-contained (i.e. not dependent on ScalaTest source) example?

        Show
        Heather Miller added a comment - As this ticket stands, this is not reproducible. It requiers a now-dated version of ScalaTest source. I dug around for a bit in ScalaTest source and Scaladoc, and it seems that JMockSugar doesn't exist any longer, so I can't get a full idea of what's really happening at this point. In general, self-contained and minimized code examples are what we need to issue a fix. Can you please submit a self-contained (i.e. not dependent on ScalaTest source) example?
        Hide
        Vlad Ureche added a comment - - edited
        $ cat A.scala
        package a {
          class A
        }
        package b {
          class A
        }
        
        $ scalac A.scala
        
        $ cat B.scala
        package a {
          class B {
            def fooA(a: A) = 3
            def fooB(a: b.A) = 4
          }
        }
        
        $ scaladoc B.scala
        model contains 3 documentable templates
        

        In the scaladoc page you'll get:

        def fooA(a: A): Int
        def fooB(a: A): Int
        

        The tooltips will indicate the correct entities (a.A and b.A) but that doesn't make it much better.
        I need to have a look at the scala type printers and see if I can reuse some of the infrastructure there.

        Show
        Vlad Ureche added a comment - - edited $ cat A.scala package a { class A } package b { class A } $ scalac A.scala $ cat B.scala package a { class B { def fooA(a: A) = 3 def fooB(a: b.A) = 4 } } $ scaladoc B.scala model contains 3 documentable templates In the scaladoc page you'll get: def fooA(a: A): Int def fooB(a: A): Int The tooltips will indicate the correct entities (a.A and b.A) but that doesn't make it much better. I need to have a look at the scala type printers and see if I can reuse some of the infrastructure there.
        Hide
        Heather Miller added a comment -

        Ah, ok, I see now-- wasn't clear to me from the description.

        So, I suppose, in an effort to support fully-qualified names being generated in some scenarios, but not in others (we don't want them generated all over the place when they don't need to be) we could at the entity-level: check if there are two or more types that appear with the same name, if so, compare the fully-qualified names, and append the prefixes to the entity name as follows:

        scala.collection.immutable.HashMap -> immutable.HashMap
        scala.collection.mutable.HashMap -> mutable.HashMap
        org.scalay.collection.immutable.HashMap -> org.scalay.collection.immutable.HashMap
        

        It's certainly possible, but the way I see to do it is to, as we produce the page template in Template.scala for a given entity, collect the fully-qualified names of every type/entity we encounter (i.e. param lists of members, return types, etc) in a Set or something private and top-level in Template.scala. But then the issue is that afterwards, we'd need to make a second pass through the whole page and rewrite duplicate-named entities with the qualified/fully-qualified names, where necessary. ...Which would require a larger refactoring... (Unless there's an easier way to do it that I'm missing, maybe in the model or something...)

        But...

        Workaround: in the meantime, one could use a use-case to insert better-qualified/fully-qualified names where needed.

        Show
        Heather Miller added a comment - Ah, ok, I see now-- wasn't clear to me from the description. So, I suppose, in an effort to support fully-qualified names being generated in some scenarios, but not in others (we don't want them generated all over the place when they don't need to be) we could at the entity-level: check if there are two or more types that appear with the same name, if so, compare the fully-qualified names, and append the prefixes to the entity name as follows: scala.collection.immutable.HashMap -> immutable.HashMap scala.collection.mutable.HashMap -> mutable.HashMap org.scalay.collection.immutable.HashMap -> org.scalay.collection.immutable.HashMap It's certainly possible, but the way I see to do it is to, as we produce the page template in Template.scala for a given entity, collect the fully-qualified names of every type/entity we encounter (i.e. param lists of members, return types, etc) in a Set or something private and top-level in Template.scala. But then the issue is that afterwards, we'd need to make a second pass through the whole page and rewrite duplicate-named entities with the qualified/fully-qualified names, where necessary. ...Which would require a larger refactoring... (Unless there's an easier way to do it that I'm missing, maybe in the model or something...) But... Workaround: in the meantime, one could use a use-case to insert better-qualified/fully-qualified names where needed.
        Hide
        Vlad Ureche added a comment -

        That's the idea, but we need to do it earlier. In the example I posted, the template pages for a.A and b.A are not generated so recording names in Template.scala won't buy us much. On the other hand, scalac symbols are being generated for both A-s, so we should move the logic to the model factory. That's why I wanted to have a look at how the error printers in Scala work, maybe I can reuse their logic.

        How would you work around this with use cases?

        Show
        Vlad Ureche added a comment - That's the idea, but we need to do it earlier. In the example I posted, the template pages for a.A and b.A are not generated so recording names in Template.scala won't buy us much. On the other hand, scalac symbols are being generated for both A -s, so we should move the logic to the model factory. That's why I wanted to have a look at how the error printers in Scala work, maybe I can reuse their logic. How would you work around this with use cases?
        Hide
        Vlad Ureche added a comment -

        Fixed in f916434c.

        Show
        Vlad Ureche added a comment - Fixed in f916434c .

          People

          • Assignee:
            Vlad Ureche
            Reporter:
            Darlene Wallach
            TracCC:
            Bill Venners
          • Votes:
            0 Vote for this issue
            Watchers:
            5 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development