scott wrote:
>> The *other* problem is that Haskell libraries tend not to be very 
>> documented. :-(
> 
> As Darren said, even if you add no documentation to your code at all, 
> you still get to see the parameter type and name that the library 
> programmer used in the pop-up help, which usually is enough to figure 
> out what to do - unless they did something stupid like "float 
> Rotate(float a, float b)" :-)
> 
> Adding documentation to your code is really easy too, you can just type 
> "///" before a function definition and it will automatically insert a 
> template for you to add some text to say what the function does and add 
> some help text for each parameter.  Obviously this then shows up in the 
> auto-complete pop-up when you use that function.
> 
> There are also documentation builder programs that will scan all your 
> code source files for these special "///" comments and automatically 
> build one of the MS Help files for you.  I have never done this, but it 
> if I was to release some library it would be a matter of seconds to 
> generate the documentation file.

Haskell too has a document autogen tool. Unfortunately, if the 
programmer didn't bother to write any comments, all you'll get is a list 
of function names and type signatures. Sometimes that really is all you 
need - but sometimes it isn't...

Also, all too often when trying to use a complex library, what you need 
is a high-level overview of the library's design before you start 
reading low-level documentation for individual functions. This is almost 
never available.

Post a reply to this message