Possible clash with index.html and a top-level name index

[sethladd]

Consider the case where a library has a top-level name called index.

This will clash and overwrite the index.html we generate inside the directory for the library docs.

[sethladd]

Some ideas for solutions:

Under the directory for the library:

lib_name/
  index.html
  classes/
    Foo.html
  enums/
    Foo.html
  properties/
    foo.html
  functions/
    foo.html
  ...etc...

Nice thing about this, is that we would no longer need to append _class to the filename of classes.

[devoncarew]

One other thing to consider is that these docs will be hosted in a number of different places (api.dartlang.org, random github.io pages, dartdocs.org, ...) and IDEs and other tools will want to be able to construct URLs that point to libraries/classes/members in order to jump to hosted docs. So having a simple, reproducible scheme to map from a library/symbol/member to a URL or path would be a good thing.

For things like storing into a properties directory, IDEs would have to replicate the logic to know when something would be considered a property.

Some things we could take advantage of are that

• library names within a package are relatively unique
• file names within a package are definitely unique
• symbol names in a library are unique

Here's a possible layout:

package_name/
  index.html
  lib_name_1/
    topLevelFunction.html
    Cat.html
    Dog.html
    Dog-bark.html
  lib_name_2/

[devoncarew]

or:

package_name/
  index.html
  lib_name_1.dart/
    topLevelFunction.html
    Cat.html
    Dog.html
    Dog-bark.html
  lib_name_2.dart/

[sethladd]

@keertip what was the case that forced us to append _class to the end of class names? What did it conflict with?

[sethladd]

Would an IDE know the filename (e.g. lib_name_1.dart ?) for a symbol it would run across in source code?

I'm hesitant to bake in the file name into a URL structure that should otherwise use "logical" names. The file name seems like an implementation detail.

I'm leaning towards #585 (comment)

[sethladd]

I found it: "There was a case where the library (path) had a property and class of the same name, and so dartdoc was not getting the links right."

More specifically, there is a getter called style and a class called Style. In a case-insensitive file system, these will clash.

There's a generalized issue here: Dart has case-sensitive names, but file-systems don't necessarily. In Dart, you can do:

class Foo { }
class foo { }

So, what's a generalized solution to creating filenames that never clash, yet are still SEOable and still logically discoverable?

Some research:

• javadoc will happily overwrite the same file, if two class names are the same modulo casing
• rdoc will happily overwrite the same file, if two class names are the same modulo casing

I think we need to worry about not clashing with files we introduce (like, index.html) and not clashing with similar names of the same "type" (class, function, etc).

We should support this:

doIt(x) => x;
class DoIt {
}

and generate two files.

I don't think we need to support:

class DoIt { }
class DOIT { }

The requirements I can come up with are:

• file layout shouldn't clash with files that dartdoc introduces (like index.html)
• names of different types[1] shouldn't overwrite each other, when they are similar modulo case sensitivity
  e.g. top-level function doIt() should generate a filename that's different than class DoIt
• names of the same type may overwrite themselves (based on what other tools do)
  e.g. if someone does class DoIt{} and class DOIT{}... well, too bad :(
• the algorithm for converting a name into a doc Uri path should be intuitive

I believe we need to, at a minimum:

• move our index.html file elsewhere or do something else to create the index for a library
• stop appending _class to classes because that's otherwise a valid name (consider a top-level function: doIt_class. this would clash with a DoIt class)

[1] types == function, class, property, etc

[keertip]

So how about

pkg_name/
  index.html
  lib_name_1/
    lib_name_1.html // the index
    top_level_fn.html
    property1.html
    property2.html
    classA.index.html
    classB.index.html
    classA/
      classA.html // constructor
      method1.html
    classB/
       classB.html
       propertyZ.html

The index for the library need not be called index.html, we can use the library name instead. We can also append index to the index files for library and class to make it unique.

We could also use the file name for the library index, then the IDE will not have to special case for anonymous libraries.

[sethladd]

index.html is really helpful at the top-level, would like to keep that if possible.

Could a top-level name ever be the same as a library? If so, not sure we could create lib_name_1.html

@devoncarew wanted to keep it "easy" for tools to take a name and construct a URL to the docs. Would classA.index.html be easy? (or, classA-index.html)

In general, using - creates nicer looking URIs than . but either will technically work.

[keertip]

There is no rule that says the library name is unique, so maybe we could do file_name-index.html for libraries and class_name-index.html for classes?

[keertip]

@sethladd, @devoncarew

So go ahead with index.html for package and file_name-index.html for libraries and class_name-index.html for classes?

[sethladd]

Looking at #585 (comment) I think we'd potentially get a clash with a library name and a class name. Class names and library names can clash, can't they?

So, putting lib-index.html and class-index.html into the same dir might create a clash.

We could do libname-library.html and classname-class.html to avoid a dupe.

[keertip]

sgtm!