[Haskell-cafe] Haddock and the qualified imports
Hi, I noticed some time ago the fact that qualified imports doesn't affect the generated documentation. It's kind of clumsy in case of libraries that define a lot of synonyms (vector and bytestring come in my mind first). For instance, in the package utf8-string: http://hackage.haskell.org/packages/archive/utf8-string/0.3.7/doc/html/Data-ByteString-UTF8.html Here, the documentation doesn't say that the utf8-string/Data.ByteString.UTF8.ByteString datatype used all along comes in fact from Data.ByteString. If it were instead a new implementation of ByteString (as for bytestring/Data.ByteString.Char8.ByteString) the documentation would look exactly the same, so to disambiguate to reader has to crawl through the code to get to the initial definition. (clicking on a 'ByteString' doesn't even redirect you to the original bytestring/Data.ByteString page) It should be written that this 'ByteString' is not a newly defined type but instead a re-exportation. It's even worse when you see the doc of a module that uses in the meantime lazy and strict ByteStrings, or normal and unboxed/storable/insert flavour here vector: you have to hover the type name to see which haddock page it points to. In that case, a solution might be to indicate on top of the doc page that it uses another module as a qualified import, and to keep the prefixes in the function signatures. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
2011/12/6 Yves Parès limestr...@gmail.com: Hi, I noticed some time ago the fact that qualified imports doesn't affect the generated documentation. It's kind of clumsy in case of libraries that define a lot of synonyms (vector and bytestring come in my mind first). For instance, in the package utf8-string: http://hackage.haskell.org/packages/archive/utf8-string/0.3.7/doc/html/Data-ByteString-UTF8.html Here, the documentation doesn't say that the utf8-string/Data.ByteString.UTF8.ByteString datatype used all along comes in fact from Data.ByteString. If it were instead a new implementation of ByteString (as for bytestring/Data.ByteString.Char8.ByteString) the documentation would look exactly the same, so to disambiguate to reader has to crawl through the code to get to the initial definition. (clicking on a 'ByteString' doesn't even redirect you to the original bytestring/Data.ByteString page) It should be written that this 'ByteString' is not a newly defined type but instead a re-exportation. It should be simple to add some kind of Re-export of link to original thing tag to the Haddock documentation. Feel free to add a ticket for this feature to the issue tracker (trac.haskell.org/haddock) with a description of how it should work. It's even worse when you see the doc of a module that uses in the meantime lazy and strict ByteStrings, or normal and unboxed/storable/insert flavour here vector: you have to hover the type name to see which haddock page it points to. In that case, a solution might be to indicate on top of the doc page that it uses another module as a qualified import, and to keep the prefixes in the function signatures. Maybe. But have you tried experimenting with Haddock's --qual flag? David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
I'll try that. But if it does this, why isn't the documentation on hackage generated with that option? (Sorry, I was mostly talking about it, since I don't always install documentation locally, I check it on hackage) 2011/12/6 David Waern david.wa...@gmail.com 2011/12/6 Yves Parès limestr...@gmail.com: Hi, I noticed some time ago the fact that qualified imports doesn't affect the generated documentation. It's kind of clumsy in case of libraries that define a lot of synonyms (vector and bytestring come in my mind first). For instance, in the package utf8-string: http://hackage.haskell.org/packages/archive/utf8-string/0.3.7/doc/html/Data-ByteString-UTF8.html Here, the documentation doesn't say that the utf8-string/Data.ByteString.UTF8.ByteString datatype used all along comes in fact from Data.ByteString. If it were instead a new implementation of ByteString (as for bytestring/Data.ByteString.Char8.ByteString) the documentation would look exactly the same, so to disambiguate to reader has to crawl through the code to get to the initial definition. (clicking on a 'ByteString' doesn't even redirect you to the original bytestring/Data.ByteString page) It should be written that this 'ByteString' is not a newly defined type but instead a re-exportation. It should be simple to add some kind of Re-export of link to original thing tag to the Haddock documentation. Feel free to add a ticket for this feature to the issue tracker (trac.haskell.org/haddock) with a description of how it should work. It's even worse when you see the doc of a module that uses in the meantime lazy and strict ByteStrings, or normal and unboxed/storable/insert flavour here vector: you have to hover the type name to see which haddock page it points to. In that case, a solution might be to indicate on top of the doc page that it uses another module as a qualified import, and to keep the prefixes in the function signatures. Maybe. But have you tried experimenting with Haddock's --qual flag? David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
2011/12/6 David Waern david.wa...@gmail.com: 2011/12/6 Yves Parès limestr...@gmail.com: It should be written that this 'ByteString' is not a newly defined type but instead a re-exportation. It should be simple to add some kind of Re-export of link to original thing tag to the Haddock documentation. Feel free to add a ticket for this feature to the issue tracker (trac.haskell.org/haddock) with a description of how it should work. I should really add as well that if you contribute patches that will increase the likelyhood of this being added in the near future from ~0% to 100% :-) In general I'd like to encourage anyone interesting in hacking on small useful projects for the benefit of the Haskell community to take a look at the Haddock trac. It's got a lot of nice little feature requests that no one is working on. In general we're not seeing that much new development in Haddock at the moment. I am (as the maintainer) mostly spending my time fixing bugs, making releases and so on. If anyone feels like helping out, please talk to me. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
I've long wanted a display it like I typed it option, e.g. if I typed 'Module.function' the link would look exactly like that. I've also often wished that unimported but fully qualified modules like 'Data.List.partition' would link even if Data.List is not imported. I suppose similarly to the way that s blind link without having to know about the module in question. And speaking of s, I've always wondered why double quotes were needed for module names, and why single quotes around capitalized words isn't sufficient. But I also always assumed that the answers were probably all not enough people sending patches so they just went on my personal list of things to look at if I ever had some extra time. On Tue, Dec 6, 2011 at 5:36 AM, David Waern david.wa...@gmail.com wrote: 2011/12/6 David Waern david.wa...@gmail.com: 2011/12/6 Yves Parès limestr...@gmail.com: It should be written that this 'ByteString' is not a newly defined type but instead a re-exportation. It should be simple to add some kind of Re-export of link to original thing tag to the Haddock documentation. Feel free to add a ticket for this feature to the issue tracker (trac.haskell.org/haddock) with a description of how it should work. I should really add as well that if you contribute patches that will increase the likelyhood of this being added in the near future from ~0% to 100% :-) In general I'd like to encourage anyone interesting in hacking on small useful projects for the benefit of the Haskell community to take a look at the Haddock trac. It's got a lot of nice little feature requests that no one is working on. In general we're not seeing that much new development in Haddock at the moment. I am (as the maintainer) mostly spending my time fixing bugs, making releases and so on. If anyone feels like helping out, please talk to me. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
2011/12/6 Evan Laforge qdun...@gmail.com: I've also often wished that unimported but fully qualified modules like 'Data.List.partition' would link even if Data.List is not imported. I suppose similarly to the way that s blind link without having to know about the module in question. That's just been fixed - it's just been a long standing bug. And speaking of s, I've always wondered why double quotes were needed for module names, and why single quotes around capitalized words isn't sufficient. That would refer to a type or data constructor! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
On Tue, Dec 6, 2011 at 11:51 AM, David Waern david.wa...@gmail.com wrote: 2011/12/6 Evan Laforge qdun...@gmail.com: I've also often wished that unimported but fully qualified modules like 'Data.List.partition' would link even if Data.List is not imported. I suppose similarly to the way that s blind link without having to know about the module in question. That's just been fixed - it's just been a long standing bug. Whoohoo, good to hear! I've always written those links in my docs, under the hope that they would some day start working :) And speaking of s, I've always wondered why double quotes were needed for module names, and why single quotes around capitalized words isn't sufficient. That would refer to a type or data constructor! Well, it could look at the filesystem and tell them apart, right? I suppose you're right, it's ambiguous if there's both Data.hs:data List = ... and Data/List.hs. I guess what really trips me up is that s blink link feature means it will try to turn all sorts of improbably things into module links. It might be enough to check for Camel.Dots.Words to reduce the amount of manual quoting you have to do. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
