On Thu, 23 Mar 2000, Volker Wysk wrote:
> (Message didn't get through the first time. Reposting.)
>
>
> Hi
>
> What you suggest sounds like a solution that's easy to learn, useful, and
> can be implemented with modest effort. It might be the a good solution
> for the problem at hand, documenting the haskell libraries.
>
> However, if one would take this way, one should keep the tool
> simplicistic. Or you could end up defining just another ad hoc tag syntax
> for just another literate programming system.
The viewing tasks that I listed before do not sound
simplistic to me at all. These are the things that I
need for daily programming. Frankly, I am not interested
in anything more than that.
I tried to put an idea across that we do not need any
tags whatsoever for any of those facilities.
I really mean it. Neither XML based nor home grown, such as
triple-dash suggested by Manuel or double stars of Sun - as
used in Java.
/**
*
* They say that the double star supposes to signify
* the importance of this comment for documentation.
*
*/
I say that any comment that is not properly positioned
in the module structure should be ignored. It is not
worthy of our attention; it either signifies an
implementation hack or its author's frivolity. We only need
one type of comments - good and important comments.
The rest is a trash. If you accept this, the double
star is gone. We just got rid of one tag.
As you well know, a Haskell module must conform
to a very specific structure -- as defined in Haskell
Report. No one complains that the import clause must
be positioned just after the module declaration.
Optional exports go in between. Definitions of infix
operators must be at the top of module too.
Now imagine that we all agreed on how we structure
the comments as well, and extended a module formal
definition to accomodate the (important) comments.
I see only a need for two or three types of comments.
Module comments just after exports. Function comments
just after the function signatures. Possible
class comments just after a class declaration.
Maybe data/newtype/type comments too...
I say "after", not "before". For Ross and Manuel
the "before" seems to be the obvious and natural
solution. For me it is not -- and for variety of
good reasons. One reason is logical: I am accustomed
to seeing a title of a book/work/program first, and
then the preface, summary, introduction, etc.
This translates to "formal definition/name first,
explanation later". If I do it other way around
then I find myself in a typical "C" trap:
/**
*
* Function: void fillToBorder (
* Point p,
* Color fillColor,
* Color borderColor);
*
* Formalized or very loose comment here: with or
* without special tags.
*
*/
void fillToBorder (
Point p,
Color fillColor,
Color borderColor)
{
...
}
My experience teaches me that more often than not
programmers change their mind and modify the
number of arguments to their functions. And they
often forget to modify the comments above their point
of focus. From then on the original comments are not
only useless but also misleading if extracted
as API.
The second reason for my preference to "after" approach
is informative. I can use the names of arguments to
write the clear comments:
void fillToBorder (
Point p,
Color fillColor,
Color borderColor)
{
//
// Flood a portion of the image with `fillColor',
// beginning at point `p' and stopping at
// `borderColor'.
//
....
}
Notice that if I change my mind to redefine the above
function, the next natural thing for me to do is to
change comments below the signature. No discrepancies!
The third reason for my preference to "after" approach
is purely technical. I can easily convince my parsing
tool to switch to "comment state" right after it
found the function signature. And if it cannot find any
comment here - there will be no comments in API
documentation. Tough luck!
How about Haskell version of the above?
fillToBorder :: Point -> Color -> Color -> IO ()
Contrary what some people think, the signature
itself does not tell the full story. Here I can guess
the kind of action to be performed, but I am not
sure which Color represents border color.
So we need some comments here. The separation
of the signature from the function definition
in Haskell is a blessing and a curse in the same
time. I was experimenting with few ways of documenting
Haskell functions and what I usually do is this:
fillToBorder :: Point -> Color -> Color -> IO ()
fillToBorder p fillColor borderColor =
--
-- Flood a portion of the image with `fillColor'
-- beginning at point `p' and stopping at `borderColor'
... body of the procedure ...
A question arises: what portion of the above should
be extracted for API documentation purposes? I suppose
-- all five lines. What about `=' sign? How about
functions written with guards?
But, with enough effort, both "before" and "after"
varieties can be handled by any well designed tool.
I did it in my Xcoral-java extractor to accomodate
both versions. And I am by no means an expert in
parser designing.
>
> I strongly disagree with the idea of incorporating any documentation
> generation facility into the language, or the compiler. The compiler's job
> is to produce good executables, not documentation. As has been noted, the
> GHC team can't "solve all programming problems in the world".
I did not suggest this at all. In contrary!
I said: write well structured, readable, pure ascii
Haskell modules. You can then read them, exchange them,
trust them. Tools will be welcome, but they do
not have to be written by GHC team.
>
> What the compiler, or some other tool that comprehends the Haskell syntax,
> could do, is provide a way to read the source code, and output it again,
> with some of the structure made explicit by inserting (XML-) tags. This
> output could then be used by a documentatin generation tool, such as an
> Eiffel-like one.
I have no problem with this idea at all. This is an enhacement
of the basic source code to produce variety of views. My
Xcoral-java class hierarchy browser does just that. It reads
the pure, _nontagged_ ascii representation of a set of Java
classes. If tags exist, they are ignored. It creates the
internal representation of those classes - with dependencies,
package and import information, signatures and so on.
And it displays a lot of interesting stuff. I do not have
any of its snapshots handy, but you are welcome to view
pictures from its cousin -- "RemoteClassBrowser".
www.numeric-quest.com/news/RemoteBrowserCapture.html
This should give you the idea what can be done
without tags.
But such extractor could then spit out the XML code
as well. Maybe not as rich as you would like it to be
but reasonably rich nevertheless.
>
> This way, you could separate the language specific task of making sense of
> the code, from the documentation generation system. After all, the general
> problem of producing program documentation is not Haskell specific at all.
No, but it helps to use Haskell awared tools. For example
a good extractor running in Hugs could supply missing
signatures, if we wanted to go so far.
> [cut]
Friendly,
Jan
