Hi,

I'm I just not reading/understanding this correctly, or is it indeed a documentation bug (in which case I'll file a bug report with a patch).

http://www.freepascal.org/docs-html/rtl/classes/tstream.readbuffer.html

The "short description", as far as I'm concerned, is completely wrong for TStream.ReadBuffer. It reads as follows:

"Reads data from the stream to a buffer"

It seems to me that it describes the flow of data going from the stream to the buffer parameter. But that is what TStream.WriteBuffer() does, not ReadBuffer()??

Then in the "long description" in correctly explains the method.

"ReadBuffer reads Count bytes of the stream into Buffer. If the stream "does not contain Count bytes, then an exception is raised."

Also compare the short descriptions of .ReadBuffer and .WriteBuffer - they seem to be saying the same thing. So it seems there was a copy-and-paste error when the documentation was written.

The explanation is correct.

ReadBuffer actually reads data from the stream to the buffer. Just like read.

Just like you read from a file. Data goes from the file to your variable.

Michael.

ReadBuffer actually reads data from the stream to the buffer. Just like read.

Sorry, I got my email all twisted - to many open windows at the same time.

My issue is with the TStream.WriteBuffer's short description. It reads as follows...

"Writes data from the stream to the buffer"

And now the Kylix 3 description of TStream.WriteBuffer.

"Writes Count bytes from Buffer onto the stream and advances "the current position of the stream by Count bytes."

As you can see, the FPC documentation describes the flow of data from the stream to the buffer parameter, but Kylix/Delphi describes it other way round - data from the Buffer is written to the Stream.

In FPC's docs, the WriteBuffer and ReadBuffer short descriptions are saying the same thing. Suggesting a simple documentation copy-and-paste error.

The correct short description for TStream.WriteBuffer should be something like...

"Writes data from the buffer to the stream"

...though the Kylix/Delphi short description is much better and clearer. :)

Graeme Geldenhuys wrote

...though the Kylix/Delphi short description is much better and clearer. :)

And anyone who now read that description should be very careful to modify the current description in the FPC documentation, because if the result looks too much like the Delphi description then it would be extremely hard to argue that the author came up with it independently.

In general: please do not copy/paste any text or code by Borland/CodeGear/Embarcadero on our mailing lists, fora, bug tracker etc. That is simply the nature of copyright: once you are exposed to something, you are tainted. And the more recent the exposure, the more tainted you are. There are no hard and fast rules regarding what is copyright infringement and what not (even in case of identical copies it depends on the length and nature), but not posting any direct quotes at all is always safe.

Jonas

Correct. I've adapted the text. Rev 889.

Michael.

Jonas Maebe wrote

In general: please do not copy/paste any text or code by

So what's the difference between me posting the Kylix 3 / Delphi 7 description here, or posting a link to Embarcadero's publicly visible documentation on their website? The latter has been done many many times on this and lazarus mailing lists.

Anyway, I fully understand the issue with copyright material - posting of the Kylix description was simply to highlight the problem in the FPC docs. In no means did I intend that the Kylix description must be copied verbatim into the FPC docs. I simply commented that the Kylix documentation was correct and clearer to understand.

Correct. I've adapted the text. Rev 889.

Thanks Michael.

If you post a link, people can choose to go there or not.

In no means did I intend that the Kylix description must be copied verbatim into the FPC docs.

As I tried to explain in my previous message, copyright covers much more than verbatim copying and people who read the original text get tainted.

Jonas

Jonas Maebe wrote

As I tried to explain in my previous message, copyright covers much more than verbatim copying and people who read the original text get tainted.

Once again, I fully understand. Your suggestion will only work in an "ideal world" situation though. Realistically, we don't all live in a cave - we interact with some many things ever day. Nobody is 100% untainted!.

What should be interesting, is to do a poll here and in the lazarus mailing list. Who owns or has access to a copy of Delphi or Kylix? Probably 90+% of the developers here.

On a side note:
----------------------
Now not to raise any alarms or point fingers, but I know for a fact that the person that wrote ALL the FPC documentation still works to this day with Delphi. Oops - talk about tainted! ;-) [see what I mean]

Again, as I wrote in my original message "And the more recent the exposure, the more tainted you are", and "There are no hard and fast rules regarding what is copyright infringement and what not". The point is not to be holier than the Pope. The point is to show good faith and prevent as many accidents or unwanted exposure as possible.

Jonas