From f3778be679c7a071a6b00f2878f5d093e0353bd3 Mon Sep 17 00:00:00 2001 From: simonmar Date: Wed, 10 Apr 2002 14:30:58 +0000 Subject: [haddock @ 2002-04-10 14:30:58 by simonmar] Add an introduction --- doc/haddock.sgml | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 148 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/haddock.sgml b/doc/haddock.sgml index 717c0f17..a305a2be 100644 --- a/doc/haddock.sgml +++ b/doc/haddock.sgml @@ -14,13 +14,159 @@ Simon Marlow - This document describes Haddock, a Haskell documentation tool. + This document describes Haddock, a Haskell documentation + tool. + - + + Introduction + + This is Haddock, a tool for automatically generating + documentation from annotated Haskell source code. Haddock was + designed with several goals in mind: + + + + When documenting APIs, it is desirable to keep the + documentation close to the actual interface or implementation + of the API, preferably in the same file, to reduce the risk + that the two become out of sync. Haddock therefore lets you + write the documentation for an entity (function, type, or + class) next to the definition of the entity in the source + code. + + + There is s tremendous amount of useful API documentation + that can be extracted from just the bare source code, + including types of exported functions, definitions of data + types and classes, and so on. Haddock can therefore generate + documentation from a set of straight Haskell 98 modules, and + the documentation will contain precisely the interface that is + available to a programmer using those modules. + + + Documentation annotations in the source code should be + easy on the eye when editing the source code itself, so as not + to obsure the code and to make reading and writing + documentation annotations easy. Haddock therefore uses + lightweight markup in its annotations, taking several ideas + from IDoc. + In fact, Haddock can understand IDoc-annotated source + code. + + + The documentation should not expose any of the structure + of the implementation, or to put it another way, the + implementer of the API should be free to structure the + implementation however he or she wishes, without exposing any + of that structure to the consumer. In practical terms, this + means that while an API may internally consist of several + Haskell modules, we often only want to expose a single module + to the user of the interface, where this single module just + re-exports the relevant parts of the implementation + modules. + + Haddock therefore understands the Haskell module system + and can generate documentation which hides the internal module + structure of the interface. A documentation annotation can + still be placed next to the implementation, and it will be + propagated to the external module in the generated + documentation. + + + Being able to move around the documentation by following + hyperlinks is essential. Documentation generated by Haddock + is therefore littered with hyperlinks: every type and class + name is a link to the corresponding definition, and + user-written documentation annotations can contain identifiers + which are linked automatically when the documentation is + generated. + + + We might want documentation in multiple formats - online + and printed, for example. Haddock comes with HTML and DocBook + backends, and it is structured in such a way that adding new + back-ends is straightforward. + + + +
+ Obtaining Haddock + + Distributions (source & binary) of Haddock can be obtained + from its web + site. + + Up-to-date sources can also be obtained from CVS. The + Haddock sources are under fptools/haddock in + the fptools CVS repository, which also + contains GHC, Happy, and several other projects. See Using + The CVS Repository for information on how to access the + CVS repository. Note that you need to check out the + fpconfig module first to get the generic + build system (the fptools directory), and + then check out fptools/haddock to get the + Haddock sources. +
+ +
+ License + + The following license covers this documentation, and the + Haddock source code, except where otherwise indicated. + +
+ Copyright 2002, Simon Marlow. All rights reserved. + + Redistribution and use in source and binary forms, with + or without modification, are permitted provided that the + following conditions are met: + + + + Redistributions of source code must retain the above + copyright notice, this list of conditions and the + following disclaimer. + + + Redistributions in binary form must reproduce the + above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other + materials provided with the distribution. + + + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS + IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; + OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF + THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY + OF SUCH DAMAGE. +
+
+ + + + Invoking Haddock + + + + + Documentation and Markup + -- cgit v1.2.3