diff options
Diffstat (limited to 'doc/intro.rst')
| -rw-r--r-- | doc/intro.rst | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/doc/intro.rst b/doc/intro.rst new file mode 100644 index 00000000..fcdc67f1 --- /dev/null +++ b/doc/intro.rst @@ -0,0 +1,164 @@ +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 a 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 obscure the + code and to make reading and writing documentation annotations easy. + The easier it is to write documentation, the more likely the + programmer is to do it. Haddock therefore uses lightweight markup in + its annotations, taking several ideas from + `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/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 not only non-exported entities + from the interface, but also 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, LaTeX, and Hoogle backends, and + it is structured in such a way that adding new backends is + straightforward. + +Obtaining Haddock +----------------- + +Distributions (source & binary) of Haddock can be obtained from its `web +site <http://www.haskell.org/haddock/>`__. + +Up-to-date sources can also be obtained from our public darcs +repository. The Haddock sources are at +``http://code.haskell.org/haddock``. See +`darcs.net <http://www.darcs.net/>`__ for more information on the darcs +version control utility. + +License +------- + +The following license covers this documentation, and the Haddock source +code, except where otherwise indicated. + + Copyright 2002-2010, 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. + +Contributors +------------ + +Haddock was originally written by Simon Marlow. Since it is an open +source project, many people have contributed to its development over the +years. Below is a list of contributors in alphabetical order that we +hope is somewhat complete. If you think you are missing from this list, +please contact us. + +- Ashley Yakeley +- Benjamin Franksen +- Brett Letner +- Clemens Fruhwirth +- Conal Elliott +- David Waern +- Duncan Coutts +- George Pollard +- George Russel +- Hal Daume +- Ian Lynagh +- Isaac Dupree +- Joachim Breitner +- Krasimir Angelov +- Lennart Augustsson +- Luke Plant +- Malcolm Wallace +- Manuel Chakravarty +- Mark Lentczner +- Mark Shields +- Mateusz Kowalczyk +- Mike Thomas +- Neil Mitchell +- Oliver Brown +- Roman Cheplyaka +- Ross Paterson +- Sigbjorn Finne +- Simon Hengel +- Simon Marlow +- Simon Peyton-Jones +- Stefan O'Rear +- Sven Panne +- Thomas Schilling +- Wolfgang Jeltsch +- Yitzchak Gale + +Acknowledgements +---------------- + +Several documentation systems provided the inspiration for Haddock, most +notably: + +- `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__ + +- `HDoc <http://www.fmi.uni-passau.de/~groessli/hdoc/>`__ + +- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__ + +and probably several others I've forgotten. + +Thanks to the the members of haskelldoc@haskell.org, +haddock@projects.haskell.org and everyone who contributed to the many +libraries that Haddock makes use of. |