[Haskell-cafe] Haddock changes pushed upstream

Hi all, As some of you might know, I hacked on Haddock over summer as part of GSOC. After some tedious fighting with GHC validation process and help of the guys on ghc-devs, the changes were finally pushed upstream couple of hours ago. While I'm waiting for the maintainer to make a call on the official release, you can already get the changes if you compile GHC HEAD. For those not so eager about compiling HEAD, 7.8 should be coming out the changes will be in that. You can read the brief changelog at [1] and the updated documentation at [2]. We were careful to not make changes to any existing syntax that would result in a large amount of packages breaking. If you're a package maintainer, here are some things to consider: * If your documentation looks fine how it is now, you're probably fine. Read the changelog[1] as it mentions some issues that were fixed. Amongst others, Haddock will now link qualified function names properly so that's something to look out for. * none of your documentation should get parse failures: any previously-failing documentation should now be displayed. This means that if you have parse failures, now is the time to go and fix them up or your documentation probably won't look pretty. On an upside, this means that we won't have whole Hackage packages missing documentation due to a minor mistake in one of the comments. * You no longer need to break up lists of the same type with newlines. Previously you'd get two lists merged on a single line in an incoherent mess. Now it'll be rendered properly. I know that even GHC documentation is guilty of this mistake. * You can now escape the markup properly. Before, you were very limited on how the markup could be escaped. For example, <r>> would result in a parse failure. * Bold markup added. The syntax is two underscores around what you want bold. Note, we still do not support multi-line markup. It's possible but it's a design choice not to support it. * You previously have gotten a document coverage report. We now have --print-missing-docs flag which will also tell you where the undocumented entities are: ``` ✓ misaki shana % haddock -h -U F.hs --print-missing-docs -o . Haddock coverage: 33% ( 2 / 6) in 'F' Missing documentation for: Baz (F.hs:5) Bar (F.hs:6) Foo (F.hs:7) add ``` * You can now nest paragraphs inside of lists. For most people this simply means that you can now have multiple levels of lists. We allow arbitrary nesting depth. The rules are: 4 spaces of indentation, new paragraphs have to be preceded by an empty line. ``` 1. Foo 1. Nested inside of Foo 2. Another thing inside of Foo >>> example inside of Foo example result 2. Back after Foo ``` * You can now have headings inside of your documentation rather than only for splitting up sections of your module. Example usage: ``` = Heading level one

...

...

some code example hello

== Heading level two * Hello Haddock! ``` Up to 6 ‘=’s are currently supported. LaTeX back-end only honours up to three ‘=’s but it is not an error to have >3, they'll simply be treated as 3. * You can now display enabled module extensions in the generated documentation with {-# OPTIONS_HADDOCK show-extensions #-}. * Picture syntax now documented. * You can now have the title attribute for your hyperlinks. The syntax is <link title> I think that about covers it all. Perhaps I will write a more visual guide to the new changes but please don't hold your breath! Feel free to ask questions. If you have bugs to report or features to ask for, please head to the Haddock Trac[3]. [1]: http://www.haskell.org/haddock/CHANGES.txt [2]: http://www.haskell.org/haddock/doc/html/ [3]: http://trac.haskell.org/haddock -- Mateusz K.