RE: Transmitting Haskell values
In all, I'm finding it rather difficult to find my way in the documentation (just as a data point for the documentation folks). To make the critique helpful instead of just a critique, here are a few ideas of what might have helped me (YMMV):
1. My main problem was that I have no good idea of all the installed libraries and the names defined in them (remember I'm a complete newbie to doing anything with a concrete Haskell installation). If somebody tells me to look for "Show", I have to sequentially open the indexes of all installed packages, and since I'm a newbie, I don't even know where to look first. I'd like to see a tool that gives me a unified overview of all installed packages. The tool should extend the "index.html" file in the ../doc/html directory so that it includes an entry for each installed library (probably copied from some "manifest.ihtml" file in the package directories), and it should create/extend the Haddockish doc-index-*.html files to be synopses of the doc-index-*.html files from the installed packages. If would be best if that tool were run automatically during package installation :-) (particularly for newbies who are fully occupied with learning the language and don't have much energy or time left for learning tools).
Generating a single unified index is entirely possible, given all the .haddock files for the relevant packages. I'll try to get this into the next version of Haddock. As for the rest, this is all stuff that could/should be done by the library infrastructure (which is currently in in the design stage).
2. Remove the split between "type/class index" and "function/constructor index" in the Haddockish doc-index.html file.
Yes, this is also something I'd like to do.
3. Some links in the indexes are bold, others aren't.
The bold ones represent the *original* defining module for the entity, as compared to a module which just re-exports it. However, knowing this information isn't very useful, and arguably it shouldn't be displayed to the user at all. I'll change this for the next Haddock version. Cheers, Simon
Simon Marlow wrote:
Generating a single unified index is entirely possible, given all the .haddock files for the relevant packages. I'll try to get this into the next version of Haddock.
Great! Thanks!
As for the rest, this is all stuff that could/should be done by the library infrastructure (which is currently in in the design stage).
Fine - just take it as a data point what a single user would like to see. Whatever that may be worth :-)
2. Remove the split between "type/class index" and "function/constructor index" in the Haddockish doc-index.html file.
Yes, this is also something I'd like to do.
3. Some links in the indexes are bold, others aren't.
The bold ones represent the *original* defining module for the entity, as compared to a module which just re-exports it.
Aaah... a mystery explained :-)
However, knowing this information isn't very useful,
Agreed.
and arguably it shouldn't be displayed to the user at all.
Indeed. I'd consider the original defining point of an entity to be an implementation detail: if it will work the same whether it's defined in the top-level module or in some helper module, the caller wouldn't (and shouldn't have to) care about the difference.
I'll change this for the next Haddock version.
Again, thank you! And your response was very much appreciated. Regards, Jo
I've done some hacking on Haddock to address some of these issues. Please take a look at http://www.haskell.org/~simonmar/haddock-test/libraries/ which is the library documentation as it will look in the next GHC release. Note that there is a single contents page listing all the modules with their packages, and there is a single index covering all modules in all packages. The index doesn't bogusly link to modules which don't contain the documentation for an entity (although it still lists modules with just re-export the entity). It also now keeps the distinction between different entities with the same name. There are probably some things that could still be tweaked - for instance, we've lost the text that used to appear on each package's contents page. I'm not sure where this should go, if anywhere. Please let me know what you think... Cheers, Simon
Simon Marlow wrote:
Been there, taken a look, read to go :-) One thing that I noted (and, in noting, remembered I was wondering about earlier): on the main page, some modules are links, others aren't. Is there some reason behind that? (This explanation might actually be appropriate for the front page of the index.)
Note that there is a single contents page listing all the modules with their packages,
Good!
and there is a single index covering all modules in all packages.
Seen it, checked it, no strange effects seen. I'm somewhat uneasy about the "instances" lists for type classes. This is information that's almost certainly going to be incomplete as soon as programmers start programming (and defining new instances of the classes).
The index doesn't bogusly link to modules which don't contain the documentation for an entity (although it still lists modules with just re-export the entity). It also now keeps the distinction between different entities with the same name.
I think I'm not noting the difference now... ;-)
There are probably some things that could still be tweaked - for instance, we've lost the text that used to appear on each package's contents page. I'm not sure where this should go, if anywhere.
If module hierarchy and package hierarchy are independent, there should probably be a separate documentation section for packages. If, on the other hand, packages are the top level of the hierarchy, then it might pay of to handle them as if they were modules containing the real modules.
Please let me know what you think...
Great! Regards, Jo
Simon Marlow wrote:
Generating a single unified index is entirely possible, given all the .haddock files for the relevant packages. I'll try to get this into the next version of Haddock.
But only as an option and/or addition, I hope...
2. Remove the split between "type/class index" and "function/constructor index" in the Haddockish doc-index.html file.
Yes, this is also something I'd like to do.
Hmmm, I actually prefer the current situation: If you don't even know if you should look for a type or a function, you probably have more trouble than just two indices... :-]
3. Some links in the indexes are bold, others aren't.
The bold ones represent the *original* defining module for the entity, as compared to a module which just re-exports it. However, knowing this information isn't very useful, and arguably it shouldn't be displayed to the user at all. I'll change this for the next Haddock version.
Again, I like the current situation, it saves you the trouble to look into simple "collecting modulues" (doing only imports and re-exports) by giving the user a clue where the documentation is. Cheers, S.
participants (3)
-
Joachim Durchholz -
Simon Marlow -
Sven Panne