<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
</head>
<body>
<p style="margin: 0pt;">
<span>
<span></span>
</span>
</p>
<p style="margin: 0px; "></p>
<div style="margin: 5px 0px;">
<br/>
Martin <lazarus@mfriebe.de> hat am 11. Februar 2012 um 14:59 geschrieben:
<br/>
<br/>
>[...]
</div>
<p style="margin: 0px;"> </p>
<div style="margin: 5px 0px;">
> We have 3 cases>
<br/>
> 1) correct and good documentation. No note was ever attached, or if it
<br/>
> was, then it was in error and removal is appropriate
<br/>
>
<br/>
> 2) empty or meaningless. (can be seen of a kind of wrong, but not
<br/>
> "incorrect" or "untrue").
<br/>
> We do not need a note to tell the end user "This is meaningless/empty"
</div>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;">"Empty" is clear.</p>
<p style="margin: 0px;">But it is not always clear if something is "meaningless".</p>
<p style="margin: 0px;">For example a description "loads a file" for a method LoadFromFile is like stating the obvious. But when this term is translated it becomes helpful. </p>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;"> </p>
<div style="margin: 5px 0px;">
> > 3) incorrect , untrue
<br/>
> Does not need a note. Does need immediate removal.
</div>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;">+1 </p>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;"> </p>
<div style="margin: 5px 0px;">
> > >
<br/>
> >
<br/>
> > >> Such an entry is absolutely useless without instructions *what*
<br/>
> > should be
<br/>
> > >> implemented at all.
<br/>
> >
<br/>
> > That's the problem: If someone knows that it cannot be as documented
<br/>
> > it does not automatically mean that he knows how it would be correct.
<br/>
> > Still I would prefer to be informed about a documentation error
<br/>
> > instead of letting me believe wrong things.
<br/>
> So we need a place to list those things.
<br/>
>
<br/>
> The final doc (or anything that will be in it) is not the place.
</div>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;">See the new fpdoc feature. </p>
<p style="margin: 0px;"> </p>
<div style="margin: 5px 0px;">
>
<br/>
> Then (as long as we have nothing better) use the bug-tracker. (I do not
<br/>
> favour that, but it is the better place)
</div>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;">I doubt that this is practical. Creating one bug report per item would create too much overhead. Creating bug reports with multiple entries does not work well. </p>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;"> </p>
<div style="margin: 5px 0px;">
> > Or ask on the mailing list and fix, once you got an answer
<br/>
>
<br/>
> >
<br/>
> > > It doesn't matter if it wasnt good before. Your [?] tags make it worse.
<br/>
> >
<br/>
> > I don't think so. It may be not very elegant. But you made it worse
<br/>
> > again. Why didn't you take the hint and correct the documenation? That
<br/>
> > would have been a real improvement.
<br/>
>
<br/>
> Maybe he didn't know either
</div>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;"> </p>
<p style="margin: 0px;">Mattias</p>
<p style="margin: 0px;"> </p>
</body>
</html>