Speaking of documentation

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Speaking of documentation

Chris Pressey
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've noticed some unexplained comment sentinels in various sources, but
I've also noticed that the documentation and code are in seperate files
for all of the library modules I've looked into so far.

Thanks in advance
_chris

--
"Ten short days ago all I could look forward to was a dead-end job as a
engineer.  Now I have a promising future and make really big Zorkmids."
Chris Pressey, Cat's Eye Technologies, http://www.catseye.mb.ca/
Esoteric Topics Mailing List: http://www.catseye.mb.ca/list.html


Reply | Threaded
Open this post in threaded view
|

Speaking of documentation

David Gould-2
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               510 536 1443
If simplicity worked, the world would be overrun with insects.


Reply | Threaded
Open this post in threaded view
|

Speaking of documentation

Mickael Remond-2
In reply to this post by Chris Pressey
Chris Pressey (cpressey) 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've noticed some unexplained comment sentinels in various sources, but
> I've also noticed that the documentation and code are in seperate files
> for all of the library modules I've looked into so far.

We are using a very simple in-house documentation tool that produces
Latex documentation of the code.

Maybe we should release this tool if you that it could serve as a basis
for further improvement.

I am also looking seriously at CCviewer: It might be great to integrate
such a doc tool with Ulf Wiger's source code browser.

I must dig deeper to see if/how this could be feasible.

--
Micka?l R?mond



Reply | Threaded
Open this post in threaded view
|

Speaking of documentation

Mickael Remond-2
Mickael Remond (mickael.remond) wrote:
> We are using a very simple in-house documentation tool that produces
> Latex documentation of the code.
>
> Maybe we should release this tool if you that it could serve as a basis
> for further improvement.

Ok. Here it is: idx-edoc-1.0

http://www.idealx.org/prj/#idx-edoc

idx-edoc is a simple automatic documentation generator for Erlang
source code.

When we will have more time, we will start working on the HTML
generation part.

--
Micka?l R?mond