[haddock @ 2002-04-04 16:23:43 by simonmar]

This is Haddock, my stab at a Haskell documentation tool.  It's not
quite ready for release yet, but I'm putting it in the repository so
others can take a look.

It uses a locally modified version of the hssource parser, extended
with support for GHC extensions and documentation annotations.

1 files changed, 47 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 00000000..7664998b
--- /dev/null
+++ b/README
@@ -0,0 +1,47 @@
+Haddock, a Haskell Documentation Tool
+=====================================
+
+This is Haddock, a tool for automatically generating documentation
+from annotated Haskell source code.  It is primary intended for
+documenting libraries, but it should be useful for any kind of Haskell
+code.
+
+Like other systems ([1],[2]), Haddock lets you write documentation
+annotations next to the definitions of functions and types in the
+source code, in a syntax that is easy on the eye when writing the
+source code (no heavyweight mark-up).  The documentation generated by
+Haddock is fully hyperlinked - click on a type name in a type
+signature to go straight to the definition, and documentation, for
+that type.
+
+Haddock understands Haskell's module system, so you can structure your
+code however you like without worrying that internal structure will be
+exposed in the generated documentation.  For example, it is common to
+implement a library in several modules, but define the external API by
+having a single module which re-exports parts of these implementation
+modules.  Using Haddock, you can still write documentation annotations
+next to the actual definitions of the functions and types in the
+library, but the documentation annotations from the implementation
+will be propagated to the external API when the documentation is
+generated.  Abstract types and classes are handled correctly.  In
+fact, even without any documentation annotations, Haddock can generate
+useful documentation from your source code.
+
+Haddock can generate documentation in multiple formats; currently HTML
+is implemented, and there is partial support for generating DocBook.
+The generated HTML uses stylesheets, so you need a fairly up-to-date
+browser to view it properly (Mozilla, Konqueror, and IE 6 should all
+be ok).
+
+Full documentation can be found in the doc/ subdirectory, in DocBook
+format.
+
+Please send questions and suggestions to me:
+
+Simon Marlow <simonmar@microsoft.com>
+
+
+[1] IDoc - A No Frills Haskell Interface Documentation System
+    http://www.cse.unsw.edu.au/~chak/haskell/idoc/
+
+[2] HDoc http://www.fmi.uni-passau.de/~groessli/hdoc/