Darren New wrote:
> Invisible wrote:
>> would be more than I just did. All I did was write a paragraph or two 
>> of documentation...)
> 
> Most open source documentation sucks. You wouldn't believe how often 
> I've seen open source documentation that says "We don't know what this 
> does, cause the guy who wrote it won't tell anyone."

Heh. Yeah, nice.

GHC falls somewhere in the middle of the scale. The documentation is far 
better than a lot of OSS projects. What it covers, it covers reasonably 
thoroughly. On the other hand, it's not exactly stellar.

GHC supports a huge number of weird and wonderful "extensions" to the 
official Haskell language, almost all of which have extremely terse 
documentation. You might argue that it's not a compiler manual's job to 
teach you how to program in Haskell. OTOH, since these are GHC-specific 
extensions, where *else* are you going to document them?

>> (But also leafing through the source code a little so I could look at 
>> the comments.)
> 
> Because having a dump of informative data with no interpretation 
> available is at all useful, right?  Don't put yourself down - you even 
> noticed it needed to be fixed.

Heh, yeah.

Of course, since the major consumer of this information is going to be 
Cabal, which is mostly developed by the same team of developers as GHC 
itself, it isn't that big a deal. Also... well, take a look at this:

  [("GHC RTS", "Yes")
  ,("GHC version", "6.10.1")
  ,("RTS way", "rts_thr")
  ,("Host platform", "i386-unknown-mingw32")
  ,("Build platform", "i386-unknown-mingw32")
  ,("Target platform", "i386-unknown-mingw32")
  ,("Compiler unregisterised", "NO")
  ,("Tables next to code", "YES")
  ]

I documented what this means. Most of it you can actually guess (and, in 
fact, I *did* guess). Only a few things really "needed" explaination.

OTOH, I added that explaination. (Which the committer than immediately 
edited again anyway.) I guess that's something. ;-)

Post a reply to this message