At 5:18p -0400 on 07 Jun 2007, Nikolay Samokhvalov wrote:
> But I suppose there are some cases when it's not possible to move the
> comment to the main text -- e.g. if the comment concerns too narrow
> area, is very specific and is useful not for all people (but still
> useful for some!).
>
> Moreover, moving good comments to the main text makes the text bloated
> -- what if we have 10 examples of using function aaa() and all of them
> are illustrations for different areas? We (ok, sorry, Tom because only
> he knows English) will choose only 1 of them to avoid bloating of the
> main text, even if all 10 use cases has some specific features...
Hrm. If they're still good comments, what about including a
hyperlink to a pop-up or separate page with some specific information
about that particular point? ("There is more <a
href='popup'>discussion on the many uses of the function aaa()</a>")
Bloat for the main documentation could still avoided, but if read on-
line (as the docs are meant to be read?) then access to other's
wisdom need not lost/weeded out.
> I could help with (yeah, not with reworking comments -- I do not know
> English well :-) ) creating a simple patch that adds a notice "this
> comment was originally created for version 8.0" and maybe something
Although, short of above, perhaps this'd be an easier en masse solution?
> BTW, then we would add some marking/rating system to the comments
> to allow other users see what comment is really useful.
Kind of like digg or something? Where the higher-rated float to the
top?
Kevin