I'm just starting to use DocC. I have a type like this:
struct Account {
enum MainType {
case asset, liability, income, expense, ...
}
let mainType: MainType
...
}
And I see that I need to refer to my symbols with suffixes:
Account/mainType-swift.property
Account/MainType-swift.enum
It's not too inconvenient, since Xcode autocompletes them, but they add noise when reading the markdown. I'm just curious - why? Obviously Swift itself is case sensitive.
There's a design tension here where web URLs are typically not case sensitive (in fact, many web services don't account for case when routing urls or indexing them in databases by default) but most (though not all!) programming language identifiers typically are case sensitive as you point out.
When designing DocC's url syntax, we felt that it was important that the web URL path and the symbol path in markdown are the same. This 1:1 relationship simplifies the implementation a bit, but primarily this is a user experience consideration. That said, case sensitivity in DocC paths is an area I'd like to see more exploration—you're not the first person who's brought up this exact example of a nested enumeration + property. I would welcome any new thoughts + ideas in this area.
Okay, good to know; thanks for the explanation.
I've started using DocC only recently, but I don't yet see much benefit for the web URL being the same as the markdown symbol. (?) To me the URL is an implementation detail, like assembly language. I will probably never care about it, but I'm going to be typing these ``...`` symbols every day. So from what I can see so far, I'd vote for some kind of name mangling scheme to translate Swift symbols into URL symbols, similar to what exists between higher level languages like Swift and C++, and assembly language.
By the way, what happens if someone does something weird like this:
func getID() ...
func getId() ...
It's probably an error to be cleaned up, but it still seems DocC should handle all legal Swift code.
For many other people, URLs are very important. They must be stable, so that links do not break when the documentation is updated. In order to support as many hosting solutions as possible, I can imagine why DocC does not rely on case-sensitivity (you may want to host a DocC package on a case-insensitive file system, for example).
Only a real care for the use cases of library developers, will allow DocC to thrive. Library developers maintain their tools for years. They paste urls to documentation in emails, support forums, and StackOverflow. They just avoid tools that fail to understand how url stability is important.
Now, I'm not sure why web URL path and the symbol path in markdown are the same. But I'll trust @jack and the team on this.
Yes, I agree that for URLs both stability and case insensitivity are worthy goals. My point is just that you can achieve both of those without exposing the implementation in the ``...`` symbols. Those can be clean Swift symbols.
This seems like it would work even with the current scheme. Why do I have to write ``foo-swift.property``? The compiler knows it's a Swift property, so it can add that suffix to the URLs when it builds the HTML.
But the current scheme of suffixes doesn't seem like it handles all Swift code. I haven't tried my getId vs getID example in DocC yet to see what happens.
... and I hope I don't sound like I'm complaining - I love this DocC project! I just moved 90% of my application code into a "[AppName]Support" Swift package just so can document it. It's really helping.
and I hope I don't sound like I'm complaining
Certainly not! This is exactly the kind of discussion I'm hoping for.
I don't yet see much benefit for the web URL being the same as the markdown symbol.
This is broadly a simplicity goal, that web url paths and symbol paths are interchangeable, easy to guess, and as stable as reasonably possible (though perhaps not always in the face of library evolution—we can implement redirects for that). I think there are potentially ways to achieve this without a 1:1 requirement, so this is certainly not immovable.
Note that generally speaking, we have a lot of flexibility on the authoring side in the compiler to accept and transform various url path forms, but we do not have that same flexibility on the web service side because our goal to provide a static site generator with easy hosting does not allow for complex url routing logic, database queries, or file existence checks.
Looking back at my notes, I recall that I originally intended for symbol paths to be case sensitive, and web urls to be case-insensitive where possible. This ended up being problematic to implement on the web side considering our requirements. Supporting case-insensitive filesystems further complicates this approach.
@robnik's suggestion of allowing some divergence between symbol paths and web urls, and making symbol paths case sensitive while encoding the case information in the web url is an interesting approach to explore.
Regarding source stability, would we always require properly capitalized symbol paths, or only when disambiguation is required?
cc @Franklin @ethankusters I'm interested in hearing your thoughts. Also I recall that pre-unified paths, the additional implementation complexity was relatively high. Perhaps ya'll could still keep unified paths but maintain 'alternative spellings' that you'd use for lookups?