 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> 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.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> What you're saying is "Python using whitespace is stupid because a lot of
>> web sites don't treat whitespace as significant." Sure, OK, that's an
>> opinion.
>
> I think it's a very valid opinion taking into account the amount of
> programming forums and blogs out there.
FWIW I've read and posted to loads of C++/C# blogs and forums, and I don't
ever recall seeing the whitespace getting messed up (it would make C+/C#
code look horrible).
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> IBM still make mainframes?
>
> Yes, they still make mainframes. Most large corporations
> still use them. It is a very profitable business for IBM.
Really? Wow. I thought people stopped making and using mainframes about
20 years ago...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
scott wrote:
> if I was to release some library it would be a matter of seconds to
> generate the documentation file.
And this, ladies and gentlemen, is why we have textbooks about libraries.
--
Darren New, San Diego CA, USA (PST)
Linux: Now bringing the quality and usability of
open source desktop apps to your personal electronics.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Invisible wrote:
>>> IBM still make mainframes?
>>
>> Yes, they still make mainframes. Most large corporations
>> still use them. It is a very profitable business for IBM.
>
> Really? Wow. I thought people stopped making and using mainframes about
> 20 years ago...
Actually, they're suing open source mainframe emulator authors lately.
--
Darren New, San Diego CA, USA (PST)
Linux: Now bringing the quality and usability of
open source desktop apps to your personal electronics.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> if I was to release some library it would be a matter of seconds to
>> generate the documentation file.
>
> And this, ladies and gentlemen, is why we have textbooks about libraries.
That and the fact that, like I said, sometimes you need an overview to
describe how the pieces fit together before you can properly understand
the nitty gritty of individual function descriptions and so on.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> Really? Wow. I thought people stopped making and using mainframes
>> about 20 years ago...
>
> Actually, they're suing open source mainframe emulator authors lately.
OK, wow. I had no idea that such things even existed. o_O
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Invisible wrote:
>>> if I was to release some library it would be a matter of seconds to
>>> generate the documentation file.
>>
>> And this, ladies and gentlemen, is why we have textbooks about libraries.
>
> That and the fact that, like I said, sometimes you need an overview to
> describe how the pieces fit together before you can properly understand
> the nitty gritty of individual function descriptions and so on.
That's exactly what I was referring to. :-)
--
Darren New, San Diego CA, USA (PST)
Linux: Now bringing the quality and usability of
open source desktop apps to your personal electronics.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Darren New <dne### [at] san rrcom> wrote:
> Actually, they're suing open source mainframe emulator authors lately.
On what grounds?
--
- Warp
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
