×
all 7 comments
sorted by:
best
topnewcontroversialoldq&a

[–]dons[S] 2 points3 points  (0 children)

Imagine a site with the haddock pages of the entire hackage/ hierarchical libraries documented.

And under any function is an 'edit' link, to add or improve the documentation on the page, which yields a patch sent in to libraries@ to be applied.

[–]gwern 1 point2 points  (3 children)

I've suggested a similar idea on Haskell-cafe: http://www.haskell.org/pipermail/haskell-cafe/2009-January/053754.html

The idea is one would do a darcs get of whatever library, mv it into a gitit dir/, and then run gitit in dir/. Now there's a web interface which lets people edit any repo-tracked file (dir/repo/*).

Of course, there's nothing stopping users of that wiki from editing stuff besides the haddocks (although one certainly hopes they will stick to doc changes). But here's the cool part: because each wiki edit is a full-fledged patch, and the wiki's dir/repo/ is presumably tracking the main library repo, any patch from the wiki should be directly applicable to the main library repo.

So then someone can, every day or two, visit the wiki and review all the patches. He obliterates the bad ones, and he will either darcs push or darcs send all the good ones to the main repo!

My problem with dons's basic idea is that while I see how you could strip all the code out of files and just leave the Haddocks behind for people to edit, I don't see how you could create a patch from this docs-only-file which could be used by libraries@ on the original Haskell sources. There're ways (perhaps each function/type is its own page or edit-section a la mediawiki, and there's some complex jiggery that associates each section with the original comment), but none that strike me as reasonably implementable.

[–]jfredett 0 points1 point  (1 child)

Granted this is an old comment, but there's a delightfully simple solution to the problem you cite w/ dons' approach.

The wiki would look something like haddock pages now, and clicking the 'edit' link would simply scrape the actual code for the haddock doc part and leave the rest alone, upon committing changes, it would change the actual file (as per your suggestion) and record a patch.

The interface would handle preventing people from deleting code, and you still get the lovely web 2.0 approach to library documentation writing...

[–]gwern 0 points1 point  (0 children)

Some sort of filter is possible, yes, with plugins. (There're pre-view and pre-save hooks one could use.)

But again, how does one actually do that? If I filter out anything not starting with -- or {-, and I wind up with '-- foo' coming from line 56, how does my plugin know to take the new '-- bar' and replace line 56's '-- foo'? Do I try to use haskell-src-exts's new features, preserve the comments & their positioning, store that somewhere ('line 1 of the edit field was originally line 56; line 2 of the edit field was originally line 112; line 3 of the edit field was originally line 521...'), and then substitute back in?

That sounds pretty challenging, and I'm not sure it's secure either: if the line-line map is stored in the client, it could be tampered with and a dumb plugin would overwrite the original lines which would be a problem even if we automatically wrap everything in comments to prevent literal code injection. ('What's that, evil's hacker's browser? You say this new comment was originally at line 1, the module header? OK then, I'll overwrite line 1 right away!')

[–]largos 0 points1 point  (0 children)

I think a meat-space solution would get us close enough without worrying about the security / reliability issues of automatically integrating wiki changes back into a source repository.

I envision haddocks where each portion (where portion is defined in some sensible manner -- paragraphs, functions, types, etc..) is associated with a comment thread, exactly as was done with Real World Haskell. This does a few things: * It clearly separates the author's documentation from those of commentors. * Any reader can immediately make a note without worrying about the repercussions of their actions. * The comments areas can be used for discussion that would not be suitable content for an API document directly.

This does mean that the comments would need to be tracked in some additional data store somewhere, but there is code available to do this (specifically, the RWH publishing system).

[–]dons[S] 0 points1 point  (0 children)

See also this ticket: http://trac.haskell.org/haddock/ticket/72

[–]nanothief 0 points1 point  (0 children)

I would love anothing that would improve haskell documentation. Sure the core is good, but a lot of hackages have almost no documentation. Even Test.QuickCheck has no documentation in its documentation page , and that is a very common library. I know about the real manual, but there is no indication it exists if you are browse the standard libraries and click on the Test.QuickCheck link