Again I found almost all of my notes removed from the LCL documentation. If this is how my work is honored, I see no reason why I should spend any more time with contributing to the Lazarus documentation :-(

When somebody is not happy with notes about wrong or missing documentation in the final docs, a feature (tag?) should be added to FPDoc, allowing for editor notes and to show or hide these in the final docs.

DoDi

Would be nice in an open source project to have means to the documentation to be developed in community.

I'm freak sure that lot of people knows a lot of examples and cases of use that could help a lot, a lot of people. A lot sure, hihi.

The problem is always how to organize that, and in that, i strongly suggest some kind of database. Documentation direct in the code is always hard to format and hard to keep a sense of unity and integrity. And on a open source project must be some means of multiple contribution, some times even multiple ways of views of the same matter. Another challenge lays on that, how to keep multiple views of the same matter. After all, what helps one, sometimes doesn't helps other.

Well, this are ideas about documentation.

Hi DoDi,

Hans-Peter Diettrich wrote

Again I found almost all of my notes removed from the LCL documentation. If this is how my work is honored, I see no reason why I should spend any more time with contributing to the Lazarus documentation :-(

I believe you posted this to the wrong mailing list. You talk about LCL docs, but this was read in the fpc-devel mailing list. My reply will go to both mailing lists.

When somebody is not happy with notes about wrong or missing documentation in the final docs, a feature (tag?) should be added to FPDoc, allowing for editor notes and to show or hide these in the final docs.

Just a suggestion... Can't you use the XML comment tag eg: < !-- aoeu -- > (spaces added so as not to screw with HTML email clients)

Though, I don't believe Lazarus's FPDoc Editor will show you those. Maybe that could be another FPDoc Editor feature request.

2012/2/10, Everton Vieira :

Everton, maybe you don't know that LCL documentation is not inside the pascal source code but in separate XML files, which are kind of a database.
You can contribute for them easily by editing the files and creating a patch. The difficult part is actually writing a good quality and consistent documentation.

DoDi's idea for a new XML tag for notes is well justified IMO. You can write comments and todo-items in pascal source code, why can't you write them in document (XML) source files?

Juha

Op 10 februari 2012 12:32 heeft Hans-Peter Diettrich het volgende geschreven:

Again I found almost all of my notes removed from the LCL documentation. If this is how my work is honored, I see no reason why I should spend any more time with contributing to the Lazarus documentation :-(

What exact change(s) do you mean? What revisions?

Vincent

I crossposted the message because the second part addresses FPDoc (FPC, not Lazarus).

IMO notes should not be hidden in comments. I want them displayed also in the final docs - just as a reminder that some text is not reliable.

DoDi

Hans-Peter Diettrich wrote

Again I found almost all of my notes removed from the LCL documentation. If this is how my work is honored, I see no reason why I should spend any more time with contributing to the Lazarus documentation :-(

I removed them:

http://svn.freepascal.org/cgi-bin/viewvc.cgi?view=rev&root=lazarus&revision=35270

Sorry if you take it so badly, but I had already previously opened a topic to talk about that and you ignored it apparently. I remain with the oppinion that things like:

<descr>implement in descendants [what?]

Are not acceptable in our documentation. If you want to keep notes about things that you see in the documentation, then maybe you should create a separate file: lazarus/docs/xml/hans_peter_notes.txt and write there:

LCL.Controls.TControl.DoOnParentHandleDestruction -> what?

So that people that building the CHM and press F1 don't have to read "[what?]"

Also, many of your notes are plainly wrong, for example lclintf line 83

<p>[this looks outdated?]

It is not outdated.

Also in lclintf line 2637:

<!-- does not apply[?]
2640 StartIndex gives the index of the first point in the array to use. All points StartIndex gives the index of the first point in the array to use. All points
2641 before this are ignored. before this are ignored. 2642 NumPts indicates the number of points to use, starting at StartIndex. NumPts indicates the number of points to use, starting at StartIndex.
2643 If NumPts is -1 (the default), Polygon uses all points from StartIndex to the If NumPts is -1 (the default), Polygon uses all points from StartIndex to the
2644 end of the array. end of the array.
-->

Yes, it does apply. You wrongly commented out correct documentation so I fixed it.

I addressed a majority of the valid comments, the main missing thing being the screen/client mouse coordinates. Indeed one would need to check those.

Hans-Peter Diettrich wrote

When somebody is not happy with notes about wrong or missing documentation in the final docs, a feature (tag?) should be added to FPDoc, allowing for editor notes and to show or hide these in the final docs.

Now that's a good idea. Or simply <!-- -->

See commit 35270: General documentation cleanup removing [?]...

DoDi

I only remember that you stated that you don't like such notes.

Such an entry is absolutely useless without instructions *what* should be you can't see that yourself, then you better
keep your hands off the documentation.

You seem not very familiar with writing documentation? Notes are ignored unless brought into sight every now and then. Did you e.g. read StyleGuide.txt?

Thanks for confirming your ignorance :-(

>

@@ -81,7 +80,7 @@
<short>Draws an elliptical curve.</short>
<descr>
<p>Use Arc to draw an elliptically curved line with the current Pen.</p>
- <p>[this looks outdated?]
+ <p>
The angles angle1 and angle2 are 1/16th of a degree. For example, a full
circle equals 5760 (16*360). Positive values of Angle and AngleLength mean
counter-clockwise while negative values mean clockwise direction.
<<

If you had taken a look at Arc(), you certainly had noticed that the parameters "angle1" and "angle2" do not exist any more. Do you need better glasses?

Also in lclintf line 2637: <!-- does not apply[?] 2640 StartIndex gives the index of the first point in the array to

The same here: Where can you find an "StartIndex" parameter???

Yes, it does apply. You wrongly commented out correct documentation so I fixed it.

Do we document *existing* code, or write science-fiction?

I addressed a majority of the valid comments, the main missing thing being the screen/client mouse coordinates. Indeed one would need to check those.

You better stay away from comments which you don't understand, and leave it to people with better understanding of the matter to make *appropriate* corrections.

Sorry for my harsh wording, but your "corrections" exceed my frustration tolerance :-(

DoDi

Then we need to extend fpdoc. So we can build help (chm or other), with or without todo/notes

Yes it is true, everyone who wishes to write/contribute docs does need to see them. Even more: there is a need for an overview (like the todo list win for pascal todo)

But, any doc to the end user must not contain this. It is useless, even irritating to the help seeking user

True the entry without the note is already of little, maybe even no use. But a user seeking help, getting presented, with a out of context, single word question "What?" is worse. Remember the user does not know that this is a comment meant for the develeopper. The user assumes, that this "What" is some form of hint, that should help him understand the topic.

So we face the question what to do until such a todo-note feature exists.

That's the reason for the cross-post, after I had just this idea.

Yes it is true, everyone who wishes to write/contribute docs does need to see them. Even more: there is a need for an overview (like the todo list win for pascal todo)

I wouldn't go so far. ToDo's also are ignored frequently, as well as compiler hints and warnings, and adding such a feature will require more tools. For more comfort we should use an readily available CMS, not extend the dedicated FPDoc tools. IMO it will be more efficient when the *users* complain about strange elements in the documentation, so that finally the *competent* developers will fix these issues.

But, any doc to the end user must not contain this. It is useless, even irritating to the help seeking user

To me it's more irritating and confusing, when documentation has already been found wrong, without any according indication.

Here I think you're underrating the Lazarus users :-)

So we face the question what to do until such a todo-note feature exists.

Why not leave the notes as they are? If everybody would fix such a note, instead of discussing how to proceed, we would have nice and better documentation pretty soon ;-)

DoDi

Hi, just a regular end-user here. I just want to say I tend to agree with Martin here. I'd much rather have something like a discussion page like on a wiki for comments like that. It doesn't look good as part of the main documentation in my opinion.

Anders

Hans-Peter Diettrich wrote

I only remember that you stated that you don't like such notes.

It is not about liking, I think it is just plainly obvious that if someone downloads our software and builds our docs, presses F1 and reads [really?] it makes us look ridiculous so it is not acceptable to have that in our documentation.

Such an entry is absolutely useless without instructions *what* should be you can't see that yourself, then you better keep your hands off the documentation.

It doesn't matter if it wasnt good before. Your [?] tags make it worse.

> <p>[this looks outdated?] > It is not outdated. Thanks for confirming your ignorance :-(

...

If you had taken a look at Arc(), you certainly had noticed that the parameters "angle1" and "angle2" do not exist any more. Do you need better glasses?

function Arc(DC: HDC; Left,Top,Right,Bottom,Angle16Deg, Angle16DegLength: Integer): Boolean; {$IFDEF
IF_BASE_MEMBER}virtual;{$ENDIF}

Then just change it to Angle16Deg and Angle16DegLength. From reading "looks outdated" how am I supposed to know that you mean that the parameter name is slightlt wrong? As far as I remember I wrote this documentation, and it is not outdated, I just made a copy+paste error in the parameter name because the function is nearly identical to its twin sister from TCanvas and I was documenting both at the same time.

Hello :-)

I just want to say I tend to agree with Martin here. I'd much rather have something like a discussion page like on a wiki for comments like that. It doesn't look good as part of the main documentation in my opinion.

That's a perfectly acceptable opinion. But which solution do you prefer:
- the documentation flaws should be fixed,
- or all the notes should be hidden in the final docs?

And what chances do *you* see, that the documenation flaws will *ever* be fixed, when nobody complains about those nasty notes?

Are you happy with an incomplete and partially outdated documentation, as provided by Lazarus in the past decades?

DoDi

It is not about liking, I think it is just plainly obvious that if someone downloads our software and builds our docs, presses F1 and reads [really?] it makes us look ridiculous so it is not acceptable to have that in our documentation.

Well, my opinion is: I would prefer to have a hint that something is wrong in the documentation instead of letting me believe it is correct if it's not. It's a kind of "watch out" which lets me have a closer look when things do not work as expected. If you don't want this in the documentation then *correct* it instead of reverting back to faulty documentation.

> Such an entry is absolutely useless without instructions *what*

should be

> 's the problem: If someone knows that it cannot be as documented it

does not automatically mean that he knows how it would be correct. Still I would prefer to be informed about a documentation error instead of letting me believe wrong things.

It doesn't matter if it wasnt good before. Your [?] tags make it worse.

I don't think so. It may be not very elegant. But you made it worse again. Why didn't you take the hint and correct the documenation? That would have been a real improvement.

Then just change it to Angle16Deg and Angle16DegLength. From reading "looks outdated" how am I supposed to know that you mean that the parameter name is slightlt wrong?

If you don't know this how should others know it?

You seem to prefer the Delphi way, where no reasonable help has been provided in the last decade, while the help system was changed from WinHelp to HtmlHelp?

That's a reasonable decision, but at least Delphi/RadStudio offered to download and use the fine D7 help even for the new versions.

My viewpoint is different, I would never start using a product where I found the documenation incomplete or wrong. That's why I started to fill the gaps in the existing documentation, and to point to all those places where I could not find out the truth myself.

They are *intended* to make it *so* worse, that the gurus (Lazarus team) finally decide to contribute the required documentation, instead of only inventing new features :-]

As a doctor would say: cure the disease, not only the symptoms.

Just another idea: Can't we delay a solution to the next release? Then we can have the annotated documentation in the trunk, and a finalized version in the release branch.

I didn't want to go into details now, but the following is a good example of essential differences between Lazarus versions:

In this case it might be sufficient to only rename the parameters. Other drawing functions have changed from/between angles (as above) and arc coordinates, with both versions available in TCanvas.Arc (unit Graphics).

From reading "looks outdated" how am I supposed to know that you mean that the parameter name is slightlt wrong?

I spent much time in updating the docs to the current LCL code, removing old and inserting new parameters. When I came across such changes, I considered it a reason for a review of these procedures, to exclude or mention possibly more changes.

If I had found the description more than only *possibly* outdated, I had replaced it immediately, without adding a revision note.

Ah, another idea: can we leave revision notes in the docs, as invisible comments, to indicate when an issue has been revised?

This would require to edit the XML sources directly, what was impossible when I revised the documentation for the first time, using LazDE or FPDoc Editor. It also would require to verify that no tool removes XML comments - here I'm not so sure about LazDE, which heavily reformats the raw (unindented) XML files.

As far as I remember I wrote this documentation, and it is not outdated, I just made a copy+paste error in the parameter name because the function is nearly identical to its twin sister from TCanvas and I was documenting both at the same time.

I'm normally very careful when touching other people's texts, that's why in this particular case I left the original content in the file, and only turned the suspect part in an comment. Aren't we *both* right in our assumptions, that the Arc description was (slightly) outdated, but was still valid except for the changed parameter names? Peace? ;-)

In other (more obvious) cases I removed real crap immediately, and replaced it by more up-to-date descriptions, as far this was possible from the source code. In the case of *abstract* methods it is impossible to find out anything about the purpose and inteded implementation of a method, due to inexistent source code. I agree that [what?] is not always easily understandable, but it should be considered a *strong* invitation to the inventors of that method, to supply the missing and required information.

Next time I'll try to be more precise, using something like [what should the method do in derived classes?]
And I would be happy if such notes are not simply removed. When somebody had a look at a note, he may turn it into an XML comment, telling other contributors that the content was revised accordingly, and now is in more correct or complete state. These comments find their way into the repository, at least, even if later on some tool or the author of the note may decide to remove them entirely (as resolved).

What do you think about this idea, and those mentioned above?

DoDi

We have 3 cases

1) correct and good documentation. No note was ever attached, or if it was, then it was in error and removal is appropriate

2) empty or meaningless. (can be seen of a kind of wrong, but not "incorrect" or "untrue").
We do not need a note to tell the end user "This is meaningless/empty"

3) incorrect , untrue
Does not need a note. Does need immediate removal.

So we need a place to list those things.

The final doc (or anything that will be in it) is not the place.

Then (as long as we have nothing better) use the bug-tracker. (I do not favour that, but it is the better place)

Or ask on the mailing list and fix, once you got an answer

Maybe he didn't know either

You make it sound like answering yes to one of the question, does force a no to the other. That is not the case.

- I want the flaws fixed
- I do not want the notes

blackmail?

:-]

(apply that emoticon, to my answer too)

As a doctor would say: cure the disease, not only the symptoms.

You want the right thing, that was never doubted. And that needs no defense.

The discussion is about the way you choose

That assumes the person who knows the answer is actually looking at that doc-entry. Not necessarily the case.

Martin hat am 11. Februar 2012 um 14:59 geschrieben:

[...]

"Empty" is clear.
But it is not always clear if something is "meaningless". 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.

> 3) incorrect , untrue Does not need a note. Does need immediate removal.

+1

See the new fpdoc feature.

Then (as long as we have nothing better) use the bug-tracker. (I do not favour that, but it is the better place)

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.

> Or ask on the mailing list and fix, once you got an answer > > > It doesn't matter if it wasnt good before. Your [?] tags make it

worse.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120211/5f90ec73/attachment.html>

The notes are for the authors, not for the end user.

3) incorrect , untrue Does not need a note. Does need immediate removal.

4 ff) incomplete, misleading, inconsistent...
This is the right place for notes, telling the *experts* to let their experience shine here.

IMO you are miles away from practical documentation. Readers and writers are not kind of compilers, which throw hints, warnings or fatal errors on every word or phrase in a documentation. Most developers think that their identifiers or implementations are self explanatory. Users can have a very different experience with the same items :-(

Which of your classes is applicable to a misspelled (or renamed) reference? Including the right suggested action?

DoDi

That's why I choose a solution that produces such a lot of noise, at least in the mailing list, that chances become better for reaching the intended goal and audience. Without some pressure on the entire Lazarus team the obvious answers will be "not me!" :-(

DoDi

Notes that appear in the end user output are inappropriate.

Notes (off this kind) are communication between developers. They can and should be accessible by those users, who want to see them. But they are not content of the help.

Besides, the help system is a bad place. They are not very likely to be seen by all the developers. After all the person who knows, does not need to read the help

This is a different topic. I have not read any disagreement about the idea to improve help.

Maybe about the "need" for individual items. But even if someone does think an item does not "need" it, that does not mean, that an improved text would be rejected. It only means that the person who does not feel the need, will not do the work.

Such perception might be changed by discussion. But again notes are not the place for a discussion.

-----------
If I think the menu entry "Jump back" (history) should be renamed, but I do not have a better name, should I rename it do "Jump back [note: need better name]" ? So every user who drops open the menu will see my note? That might sound exaggerated , but is it not the same logic?

Yes the "drawing attention" is the only good think that came of it. But that only worked, because your notes were dropped, and you could complain.

Had they gone in, they would have silently disappeared. Maybe in a few month a user read them and asked... So the discussion might still have started...

So good thing they were dropped.

"Pressure" like that doesn't work. I guess you meant: Without that kind of attention, it would be ignored by most.

------------
Any way problem remains:

I have no easy reachable list off topics that need attention[1]. So I can not check if I know the answer.

That would still be the same, if the notes had gone in. I am not about to open every help topic, to see if there is a note. I would also not stumble upon any, since I do not use the help (but if I did, I would only stumble on those that I do not know the answer)

So no that we have the attention, we need to move from inline notes, to a system that allows people to contribute the info.

[1]
Entire SynEdit... Yes I an aware off

> 4 ff) incomplete, misleading, inconsistent... > This is the right place for notes, telling the *experts* to let their > experience shine here. Notes that appear in the end user output are inappropriate.

Why that? Better let the end user run into the open knife? I would prefer to see such hints if someone already found that something is incorrect or misleading. Of course, the best would be a consistent and error free documentation but as long as this is not achieved such hints are the second best IMO.

That is why I did not have topic 4. And my last answer is wrong. (I have added my original 3 cases at the bottom of the mail, as this answer requires the context.)

- Misleading (falls under 3):
equals incorrect. So it falls under 3 and should be removed. However, if the person, who founds it has the ability to add a note, then he can also immediately correct it. Knowing it is misleading, does imply knowing what it was meant to say. So rewording the existing content should be possible.

It he person is not sure, about it being misleading or not, but believes it might be. Then better ask first before adding a note

- incomplete (falls under 2, unless it makes in misleading, then falls under 3)
Does not change by adding a note.
Again, if the person knows what is missing, then he can immediately add it. Even if after adding in might still be missing some more.

- inconsistent (falls under 2, unless it makes in misleading, then falls under 3)
Same either fix, delete or ask

Now you cot me to the level where I trip myself, because rather than discussing the actual issue, we try to prove the other one wrong, by dissecting teir words and find a meaning to them that wasn't thought off :(

my previous answer is not wrong: Notes are inappropriate.

my previous answer was incomplete

It he person is not sure, about it being misleading or not, but believes it might be. Then better ask first before adding a note

So I should add a note instead: "who can clarify this, please contact me at <...> for my questions"? ;-)

Please check how much I updated myself, *without* adding notes. The notes occur only in those places, where I could *not* find the correct description myself.

And please also tell me *whom* to ask in all these remaining cases. Guess how many answers I got in the past, when sending such questions to the mailing list :-(

DoDi

However, if the person, who founds it has the ability to add a note,

then he can also immediately correct it. Knowing it is misleading, does imply knowing what it was meant to say. So rewording the existing content should be possible.

In general this is not correct. If I see that variables mentioned in the documentation do not exist in the source I don't know automatically which variables to replace them with (if any). Or when I tested things and find that it does not behave as mentioned in the documentation I also don't know how it's meant to work.

If he person is not sure, about it being misleading or not, but

believes it might be. Then better ask first before adding a note

You know that this is impractical if you need to wait for an answer each time you stumble over errors. What happens if no one has an answer (within a given time)?

I have no easy reachable list off topics that need attention[1]. So I can not check if I know the answer.

As described in StyleGuide.txt, the marks haven been choosen for simple finding, without the need for additional tools. Simple do a search in directories (lazarus/docs/xml...) for "?]" in *.xml, and navigate easily from the search results window to all occurences. You even can restrict your search to specific units. I don't see what further comfort you can expect?

DoDi

And a comment/note like "[What]" or "[Really]" Does improve that?

If anything more meaningful can be put into a note, then the person can also write it proper into the doc.

If your tests shows that it is incorrect. Well incorrect => delete.

What good is "foo does blah blah [this is wrong]" over an empty entry? Anyone who needs the old/outdated/wrong text, still finds it in SVN

I do the same from time to the, if I try to implement something, and don't understand something I need for it. Or don't know something else.

If no one answers:
Well what good is a note then, if it is meant to indicate some one needs to fix it. No one ever will (or they would have answered)

I did entirely miss that one, sorry

Well fpdoc has <notes> tags now. So [...?] notes are not needed.

Still, then xml comments, I could have found the same way. So there was no need to put the notes into final doc output. That is: not for the purpose of enabling others to find such places

On 11/02/2012 17:21, J?rgen Hestermann wrote: > In general this is not correct. If I see that variables mentioned in

the documentation do not exist in the source I don't know automatically which variables to replace them with (if any). Or when I tested things and find that it does not behave as mentioned in the documentation I also don't know how it's meant to work.

And a comment/note like "[What]" or "[Really]" Does improve that?

At least it is a hint to the user to watch out and not rely too much on the documentation.

If anything more meaningful can be put into a note, then the person

can also write it proper into the doc.

If your tests shows that it is incorrect. Well incorrect => delete. What good is "foo does blah blah [this is wrong]" over an empty

entry? Anyone who needs the old/outdated/wrong text, still finds it in SVN

Of course, it all depends on the situation but there can be parts of the documentation that give hints how it *could* be meant but nobody knows how to make it correct. Then this is better than nothing.

ask on the mailinglist....

or did your smiley mean, you intentionally did mis-understand?

Again as written before by me: If you actually have meaningful content, why a note? And as you wrote above, if you had it, you did fix or improve the doc, rather than adding such notes.

And please also tell me *whom* to ask in all these remaining cases. Guess how many answers I got in the past, when sending such questions to the mailing list :-(

Well I agree, not every question will be answered. But if not, it means no one knows the answer. That also means, there is no one who will fix a "[what?]" note. And if no one is to fix it, there is no point in putting it there.

As I said. Trying to use them to force people will not work.

Spearing for myself:
- Where I can (have knowledge and time), I will help.
- And where that does not apply, you can be certain that such notes are the last think that will make me do anything. If they had really gone in, and decision was not to remove them without fix: Well be it.

A [what?] looks to me like I downloaded a broken file, so I will waste my time on another download.

Anyway lets assume, question was raised, no one answered.

Then it is time to make sure, that something is wrong. Putting anythinc that says "might be wrong" into absolute correct docs, is bad too (IMHO worse). That is even so it only states the possibility. Any doc can possibility be wrong, no need to state that unless one KNOWS it is.

If indeed it is, we can DISCUSS, if a proper worded text should be used (at least looks more professional:
example:

The below documentation applies to an older version of the LCL. It might not be entirely accurate.

BUT, that needs to be agreed by all.

You really don't understand the reality of providing documentation :-(

Pick some of my notes, and ask the community for a clarification. Then wait...

I've found all unmarked entries correct and complete (so far), so that the next contributor can concentrate on the marked items, and knows what exactly to research. Feel free to explain an more efficient approach, towards a complete documentation.

DoDi

Em 11/02/2012, ?s 12:26, Hans-Peter

Just another idea: Can't we delay a solution to the next release? Then we can have the annotated documentation in the trunk, and a finalized version in the release branch.

Unfortunately no, because we are deploying Lazarus Svn for example with our Android support in magazines, that's something serious and our documentation in such deployment needs to look serious too. And a huge amount of people use our snapshots and svn

Ah, another idea: can we leave revision notes in the docs, as invisible comments, to indicate when an issue has been revised?.......... Aren't we *both* right in our assumptions, that the Arc description was (slightly) outdated, but was still valid except for the changed parameter names? Peace? ;-)

Yes, I agree we are both right and I am sorry if I was rude, I apologise for I should have contacted you or converted the notes into comments and I am willing to agree to a common solution, let's put the notes as XML comments or what ever other way which Fpdoc supports :)

I always edit the XML manually so I surely won't accidentally change anything

Felipe

And a huge amount of people use our snapshots and svn

Especially with 0.9.30 being rather old already and trunk having all those nice features (and let's not forget support for FPC 2.6 and newer)

> Ah, another idea: can we leave revision notes in the docs, as invisible comments, to indicate when an issue has been revised?.......... Aren't we *both* right in our assumptions, that the Arc description was (slightly) outdated, but was still valid except for the changed parameter names? > Peace? ;-) Yes, I agree we are both right and I am sorry if I was rude, I apologise for I should have contacted you or converted the notes into comments and I am willing to agree to a common solution, let's put the notes as XML comments or what ever other way which Fpdoc supports :)

The new feature of fpdoc is

<notes>
<note>Foo</note>
<note>Bar</note>
</notes>

which can be used in <element>, <topic> and <module> as Michael wrote in another mail.

Regards,
Sven

Unfortunately your notes weren't committed. So (unless, I find the mail that points to mantis and then download the patch) I cannot read them

It is not the community to answer those question (so they can if they want), it is the developers.
And so far, IF one of them knew the answer, then I have usually gotten an answer (ok my question are usually what does this or that code do)

IF no one knows... But then those notes will not add any documentation either.

If there documetation that requires a comment like incomplete then it should get it in proper language "This documentation item is not complete" (potentially why / where / nhat)

However to deserve such a comment:
- it must not be obvious to the average user that it is incomplete
- the user must benefit from this knowledge

Similar for other notes.

Again: I am not for this. But that would IMHO be acceptable

Nothing against marking then. but not in a way that goes into the final output.

Why are you changing subject?
This was not about marking entries (that possibility using comments has been mentioned before). This was about putting, things into the final end-user version.

Hans-Peter Diettrich hat am 11. Februar 2012 um
22:10 geschrieben:

[...] I've found all unmarked entries correct and complete (so far), so that the next contributor can concentrate on the marked items, and knows what exactly to research.

Great. :)
How to find these marks? Is there a pattern?

Feel free to explain an more efficient approach, towards a complete

documentation.

Is there an efficient way to find/list them?

I guess some of these marks should be converted to the new fpdoc notes.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120212/6e5be4bf/attachment.html>

Check the changes of
Revision: 35270
Author: sekelsenmat
Date: 09 February 2012 13:52:27
Message:
General documentation cleanup removing [?] and various other minor improvements
----
Modified : /trunk/docs/xml/lcl/controls.xml
Modified : /trunk/docs/xml/lcl/forms.xml
Modified : /trunk/docs/xml/lcl/graphics.xml
Modified : /trunk/docs/xml/lcl/imglist.xml
Modified : /trunk/docs/xml/lcl/interfacebase.xml
Modified : /trunk/docs/xml/lcl/interfaces/win32/win32int.xml Modified : /trunk/docs/xml/lcl/lclintf.xml
Modified : /trunk/docs/xml/lcl/lcltype.xml
Modified : /trunk/docs/xml/lcl/menus.xml
Modified : /trunk/docs/xml/lcl/stdctrls.xml

and
Revision: 33617
Author: sekelsenmat
Date: 18 November 2011 17:16:46
Message:
Documentation rework, removes aprox. 600 occurences of [?] and other non-sense from the documentation
----
Modified : /trunk/docs/xml/lcl/controls.xml
Modified : /trunk/docs/xml/lcl/forms.xml
Modified : /trunk/docs/xml/lcl/graphtype.xml
Modified : /trunk/docs/xml/lcl/grids.xml
Modified : /trunk/docs/xml/lcl/imglist.xml
Modified : /trunk/docs/xml/lcl/interfacebase.xml
Modified : /trunk/docs/xml/lcl/lclclasses.xml
Modified : /trunk/docs/xml/lcl/lclintf.xml
Modified : /trunk/docs/xml/lcl/lclproc.xml
Modified : /trunk/docs/xml/lcl/lcltype.xml
Modified : /trunk/docs/xml/lcl/ldocktree.xml
Modified : /trunk/docs/xml/lcl/lresources.xml
Modified : /trunk/docs/xml/lcl/propertystorage.xml Modified : /trunk/docs/xml/lcl/stdctrls.xml

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120212/da004eba/attachment-0001.html>

Martin hat am 12. Februar 2012 um 03:23 geschrieben:

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120212/35e6b14b/attachment.html>

See StyleGuide.txt:

Everybody can add revision marks.
I use brackets for now, to indicate passages with questionable content: [?] unclear wording, possibly wrong. Long: [what's this?] [???] unreadable or definitely wrong description.
[~] somebody else should make this proper and nice English. [!] Incompatible or wrong implementation, e.g. [Delphi incompatible!]

When such notes shall no more be added, please update this file accordingly.

One last note:
When it is unwanted or impossible to add notes to the documents in e.g. FPDoc Editor, what's the preferred procedure then? Are bug reports required, or what's the suggested way to ask for clarification or correction of incomplete or wrong documentation?

DoDi

An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120213/8bfb14ea/attachment.html>

+10000000000000000~

seriously, though!

while i agree wholeheartedly, i must also support hans-peter's methods... especially since it may very well turn me toward an better explanation of the docs...

i cannot count the times that i've been ready to "toss in the towel" simply because the documentation has been sh!t3 :? either it is required to be connected online (the worst problem) or it takes super human effort to locate, down load and configure the docs as they should be,,, i've attempted such numerous times with the base and SVN packages but have failed each and every time :?

i beg to disagree... those "tags" make it easier to find the stuff that "doesn't make sense" (eg"[what?]") and that which needs better clarification... this is what is known as teamwork ;) in other words, there /must/ be clear communication between _all_ parties... as an outsider looking in, i much prefer the "dick and jane" type books... in other, clearer, words, give it to me as basic as you can...

how else would you expect to find a notation about it? "slightly wrong" is in acceptable... especially when one is relying on the documentation for clarification...

from my POV, the above exchange and such would have been pure gobbledegook even if i had been following along closely... :(

As far as I remember I wrote this documentation, and it is not outdated, I just made a copy+paste error in the parameter name because the function is nearly identical to its twin sister from TCanvas and I was documenting both at the same time.

i see and acknowledge this but the main underlaying problem has been, finally??, identified and should be handled as needed... /even/ if it means that "notes" are visible... this allows others to handle the situation instead of just those who may have found it... i've seen more than one occasion where i've found a bug/problem that others have found before me... i have been thankful that they could show the same or a similar problem to mine...

i'm not too proud, with my 30+ years, to step back and say "show me, please" ;)

+1000000000000000000000000000000~

you get the golden "AttaBoy" award! this is a "HugeThing<tm>"... especially since you were able to point out the problem quite clearly... now the only hope is that others see it as clearly ;)

and thus the [WTF?] style nomenclature in the available docs ;)

O.M.G.!! this really had to be spelled out??? :? :? :?

Hans-Peter Diettrich wrote

My viewpoint is different, I would never start using a product where I found the documenation incomplete or wrong. That's why I started to fill the gaps in the existing documentation, and to point to all those places where I could not find out the truth myself.

+1000000000000~

+100000000000000000000000000000000000000000000~

As a doctor would say: cure the disease, not only the symptoms.

i haven't heard one of the state that but i kow i have tossed it at them numerous times :P

+100000000000000000000000!

yes and no... no because the "author" may have changed and the additional one(s) don't have the "background"...

personally, i'm a grown person... do NOT hide schtuff from me... if you do and i find out about it, you may very well loose one who cares and directs others to the product :?

> The notes are for the authors, not for the end user. yes and no... no because the "author" may have changed and the additional one(s) don't have the "background"...

One more reason why every addition should be documented immediately, before adding more new features. In a stable design the documentation (specification) *preceeds* the implementation.

personally, i'm a grown person... do NOT hide schtuff from me... if you do and i find out about it, you may very well loose one who cares and directs others to the product :?

Be cautious, such remarks may be considered as blackmail :-(

DoDi

Martin wrote

Then we need to extend fpdoc. So we can build help (chm or other), with or without todo/notes

Even better: use a help viewer that allows for dynamically switching notes on and off or even supports a verbosity level.

-Michael

*A general note: *

I am very happy to see these discussions here.

Lazarus is getting a level of maturity and public visibility that ask for decent documentation at least as much as for code improvement.

Regarding the complexity of the topic (help is necessary for for the help viewer itself (how to use), the help content itself (makeup, how to upgrade), the language, the compiler, the IDE, the LCL, the RTL, installable extensions, 3rd party extensions ...), it is most important to provide the best possible tool for help viewing. Here the ability to find the information needed (be it the most basic stuff or the most sophisticated and seldom used feature) is the most important issue. (IMHO this is one of the greatest advantages of Delphi.)

Regarding that help writing is not exactly fun, the best possible tools need to be provided for supporting the help writers.

Obviously we are on a rather good way right now :)

Thanks to all contributors !

-Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120213/991a60d9/attachment.html>

Martin wrote

Notes that appear in the end user output are inappropriate.

Unless the actively decide to see them (e.g. if they intend to become help writers).

With community based projects there is no sharp difference between users and contributor. That is the stuff they live on.

-Michael

This was my intention as well, but with a finer granularity than now offerd by <notes>. It's not so important whether such an <editor-note> tag is suppressed by the document generator, or by the viewer, it should be insertable *everywhere* into text, like <b>, and should not cause any failure of the tools which see it. It also should not be subject to possible elimination, what can happen to XML comments depending on the tools that process such files.

MS Word e.g. allows for hidden text, and used it to steer the help compiler. In XML we have the freedom to add new tags at will, the only problem are the tools, which have to deal with all these tags.

And finally it should be possible to add such notes with every tool, not only by editing the raw XML files. That's why I choose a textual representation in the first approach, until a better solution could be found *and* added to all tools dealing with the XML docs.

DoDi

Martin wrote

Documentation rework, removes aprox. 600 occurences of [?] and other non-sense from the documentation

This does make me shiver.

Who invested those many hours to check if all this in fact was nonsense ?

-Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120213/1378ac71/attachment.html>

Michael Schnell wrote

**(IMHO this is one of the greatest advantages of Delphi.)

In fact I was referencing D7, as I don't have a more recent version that I learned has a reworked (worse ? ) help system.

-Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120213/a3d0d0b7/attachment.html>

It was my work of many weeks.

DoDi

I understood that you inserted the note and somebody else considered them to be nonsense and removed them.

I guess that the svn easily allows to retrieve them and so they can somehow automatically be converted into the upcoming verbosity-sensitive notes format.

-Michael

?

to be nonsense and removed them.

I guess that the svn easily allows to retrieve them and so they can

somehow automatically be converted into the upcoming verbosity-sensitive notes format.

AFAIK Matthias already did that (look at his mails from yesterday in one of the documentation threads)

Regards,
Sven
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120213/6302c5ba/attachment.html>

>> It was my work of many weeks. >> > I understood that you inserted the note and somebody else considered them to be nonsense and removed them.

The notes were considered "not nice", that's all :-(

For code we have ToDo notes, which can be inserted in *every* place. Matthias' solution doesn't allow for that, instead all notes have to be inserted into one appended section. Unlike in printed matter, notes in help elements cannot refer to a particular place (page, line), because the layout of the text is determined later, and may even vary with the user adjustable window size.

DoDi

Michael Schnell hat am 13. Februar 2012 um 14:33
geschrieben:

They are now fpdoc notes.
I updated the StyleGuide.txt

I guess that the svn easily allows to retrieve them and so they can somehow automatically be converted into the upcoming verbosity-sensitive notes format.

fpdoc has a flag for that.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120213/2be89960/attachment.html>

[...] IMO notes should not be hidden in comments. I want them displayed also in the final docs - just as a reminder that some text is not reliable.

Reminders must be clearly marked. A simple [?] can be misleading.

Mattias

And I would also cut that into 2 categories.

To me a simple Todo does not belong to the end user. (like "Need to write an example", or "Review English grammar")

On the other hand, the following (in proper English) could be ok: "This documentation is outdated, the parameters to the function have changed." (give more info if avail)
also ok "This differs from Delphi"

To add such notes, the reviewer must have at least enough understanding, to be sure that something is wrong.
A simple "looks wrong to me" or "I don't get that at all" is not enough to add a note.

If we risk adding false notes (well it can always happen, but should be as low risk as possible) then what good are the notes? You could not trust them anyway.

---
We can always offer 2 (or more) versions of the help. With/Without notes

If the end user, could use the IDE to contribute, "writing an example" by example and by clicking in a button this were send to some pool to be checked and then incorpored, then maybe it will be very good. I know there`s a lot to be done to get such a tool, but the idea is good. In an open source project we should always thinking about to make easy and secure the process of contribute. Is better for all.

I.e. you ask for perfectly formulated and clear comments *about* the flaws in the existing documentation *only*, while the previously existing documenation is accepted in any state (misleading, incomplete, wrong...)???

Needless to say that I cannot share that VP. I don't want to write another Ph.D. thesis about the docs. See also
http://en.wikipedia.org/wiki/Copy_editing

To add such notes, the reviewer must have at least enough understanding, to be sure that something is wrong. A simple "looks wrong to me" or "I don't get that at all" is not enough to add a note.

What other solution do you suggest instead? Remove crappy or questionable content, instead of only adding a note?

If we risk adding false notes (well it can always happen, but should be as low risk as possible) then what good are the notes? You could not trust them anyway.

I see an documentation review as an invitation to improve the existing documentation. If some notes look too short or otherwise unclear, everybody is free to ask the reviewer for a clarification. As long as only I added [...] notes, it's clear who can answer related questions. When an entry was found misleading or otherwise poor, in most cases *not* the author of that part is capable or responsible for fixing it, instead people with detailed knowledge about the *subject* or *language* should put their hands on it.

We can always offer 2 (or more) versions of the help. With/Without notes

My intention was a feature in FPDoc, that allows to hide my notes, based on the clear [...] syntax. The --emit-notes option perfectly reflects that now, but only for an *out-of-line* <notes> section. A better alternative could add an tag for *inline* comments, like the existing <var> or <b> attribute tags. A <strikeout> attribute would come close to my intention, to indicate both the range of the affected text, with a note (attribute) inside the tag telling the reason why.

DoDi

Hans-Peter Diettrich wrote

Remove crappy or questionable content, instead of only adding a note?

Not a good idea. even questionable/crappy content can be used as a starter for upcoming doc writers.

So, a comment (such as [?], but plain English and more specific is a lot better ) is much more helpful on the long run.

-Michael