search

dsheets / codoc

OCaml documentation generator
34 stars 5 forks source link

Don't linkify path components. #52

Closed dbuenzli closed 9 years ago

dbuenzli commented 9 years ago

I argue that most of the time you want to get to the definition of the last component of the path (i.e. final, type, value or module). However currently codoc linkifyes each component, because of Fitts's law it makes it hard to reach that target --- especially since our type names are often called t.

When I have M2.M1.t, I really have to aim to click on that little t to get to what I want. This makes my browsing very slow and I hate that. I think you should link the whole path to the final component only (N.B. the behaviour I describe I actually ocamldoc's one).

Going up in the hierarchy is quick enough if you need to: after you got to the def scroll up once to the top and then it's all about clicking on up/up once or twice (but again it's most of the time it's not what you are interseted in).

dbuenzli commented 9 years ago

(and I won't even talk about browsing these tiny links through mobile...)

dsheets commented 9 years ago

I think the components should be linked according to file, probably. So if you use Dns.Buf.t, Dns is linked to the pack index and Buf.t is linked to type t in the file for Buf. Similar for nested modules that have their own pages. This way, at least the last 2 components are always linked together.

dbuenzli commented 9 years ago

I think the components should be linked according to file, probably.

File structure should be irrelevant in my opinion. I'd still go with only a single link: this gives you good hit targets and no chance of clicking on the wrong one because of that very tight proximity, really I don't want to aim.

What I'm clicking on most of the time is identifiers, not the structure of identifiers, we can provide other means to navigate the structure. E.g. in module toplevel links, next to up you could maybe add breadcrumbs (or a single link to the root of the package) for the module path, here we have room to make larger hit targets.

Drup commented 9 years ago

I agree with you remarks on ease of clicking, but I really like the current possibility to access any module in a path. Maybe this could be done with a small popup or something ? It wouldn't hurt non-js users or mobiles but would add the feature for others.

dsheets commented 9 years ago

File structure isn't irrelevant, though. As you said in another issue, many times submodules are used for conceptual separation and their signatures should be exposed in another location.