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

scaladoc -doc-external-uris requires incorrect file URI format

    Details

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

      Scaladoc version 2.10.1-20121211-123311-59c2649ae0

      Description

      The syntax for -doc-external-uris is:

        -doc-external-uris:<external-doc>  comma-separated list of file://classpath_entry_path#doc_URL URIs for external dependencies
      

      The test for this feature is broken because it incorrectly constructs a file URI:

      https://github.com/scala/scala/blob/master/test/scaladoc/run/SI-191.scala#L34

        override def scaladocSettings = {
          val scalaLibUri = getClass.getClassLoader.getResource("scala/Function1.class").toURI.getSchemeSpecificPart.split("!")(0)
          val scalaLib = new File(new URL(scalaLibUri).getPath).getPath
          val extArg = new URI("file", scalaLib, scalaURL).toString
          "-no-link-warnings -doc-external-uris " + extArg
        }
      

      The scheme specific part of a local file URI is "//" + file.getPath, not just file.getPath. Because the code compares the scheme specific part of the user-provided URI against the path, this will not match the specified file URI in practice.

      https://github.com/scala/scala/blob/master/src/compiler/scala/tools/nsc/doc/Settings.scala#L266

        lazy val extUrlMapping: Map[String, String] = docExternalUris.value map { s =>
          val uri = new URI(s)
          uri.getSchemeSpecificPart -> appendIndex(uri.getFragment)
        } toMap
      

      https://github.com/scala/scala/blob/master/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala#L1040

          Option(sym1.associatedFile) flatMap (_.underlyingSource) flatMap { src =>
            val path = src.path
            settings.extUrlMapping get path map { url =>
              LinkToExternal(name, url + "#" + name)
            }
          }
      

      Given that the scheme of the classpath entry URI is ignored and assumed to be file:, File<->URI/URL conversions are tricky due to things like Windows UNC filenames, and the -doc-external-uris feature doesn't currently work as specified, I think the proper fix is to change the syntax and not go through URIs or URLs at all. Because users can figure out that an incorrect file URI like file:/home/user/demo.jar is accepted, it might be considered a breaking change, though.

        Activity

        Hide
        Eugene Vigdorchik added a comment -

        Since this feature is only available in 2.10.1 it's not too late to change the implementation. Thank you for bringing this up.

        Show
        Eugene Vigdorchik added a comment - Since this feature is only available in 2.10.1 it's not too late to change the implementation. Thank you for bringing this up.
        Show
        Adriaan Moors added a comment - https://github.com/scala/scala/pull/1787

          People

          • Assignee:
            Eugene Vigdorchik
            Reporter:
            Mark Harrah
          • Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development