Speaking of documentation

[David Gould]

On Wed, Mar 07, 2001 at 12:53:37PM -0600, Chris Pressey wrote:
> Is there a supported "autodoc" facility for Erlang, where one can write
> documentation embedded in comments in the code, which is then extracted
> and processed into 'formal' documentation in HTML (or whatever)?

I like the "literate haskell style" in some flavors. Instead of the source
text being read as all code and comments specially delimited, the source
is all comments and the code is specially delimited.

There also seems to be a more formal literate style where the source is really
a latex document with the code embedded in its own \begin{code} ...
\end{code} blocks.

The following is a sample from a CGI module in haskell. This can be read
by the compiler and also by latex to product formatted documentation. It
also looks fairly easy to implement and seems reasonably readable and
maintainable.

------------------------ snippet from CGI.lhs -----------------------
%***************************************************************************
%*                                                                         *
\subsection[CGI-HTTP-Resp]{HTTP Responses}
%*                                                                         *
%***************************************************************************

The output of a CGI script is a HTTP response (part of, the server
adds additional noise), which is either some MIME content, a
redirection to some other location, or an error status.

We make CgiOut an instance of the Show class so that we don't have to
worry about the exact format of the response that is required by the
HTTP definition.

I think what we really want is to use an existential type here!

data CgiOut = Mime a => Content{content :: a}
            | ....

We are not interested in the content type, we only need to know it is
in the Mime class.

What is missing is a table of (StatusCode,Reason)-pairs such as
(503, "server busy") and (200, "Transaction ok") etc.

\begin{code}
type StatusCode = Int
type Reason = String

data Mime a => CgiOut a =
     Content{mime :: a}
   | Location{url :: URL}
   | Status{status :: StatusCode, reason :: Reason}

instance Mime a => Show (CgiOut a) where
   showsPrec _ Content{mime=mime}
    = showString "Content-type: " . showString (mimeType mime)
    . showString "\n\n"
    . shows mime

   showsPrec _ Location{url=url}
    = showString "Location: " . showString url
    . showString "\n\n"

   showsPrec _ Status{status=status,reason=reason}
    = showString "Status: "
    . shows status . showString " " . showString reason
    . showString "\n\n"
\end{code}

---------------------------- end snippet ----------------------------

Just something to think about.

-dg

-- 
David Gould                davidg@REDACTED               510 536 1443
If simplicity worked, the world would be overrun with insects.