Page 1 of 1

Documentation issue

Posted: Tue Sep 08 2020 9:13 pm
by seasoned_geek
Don't really know where to put this so putting here. Might be fixed. I have version 1.5.3 of documentation as 1.7 was not yet available for download.

https://www.logikalsolutions.com/wordpress/wp-content/uploads/2020/09/plaintextinsert.png

The example code is calling insertText() not insertPlainText()

Yes, I'm picking a nit.

Re: Documentation issue

Posted: Tue Sep 08 2020 11:03 pm
by barbara
A bit odd you were using 1.5 docs which I am guessing you obtained these from our copperspice download page. We did have DoxyPress generated documentation for both 1.5.x and 1.6.x and this was updated to 1.6 and 1.7 today. The online API docs have been updated and display only the CS 1.7 documentation.

In terms of your comment indicating there is an issue with the example. Our docs are in fact correct. If you read just above the code, the docs say that calling QPlainTextEdit::insertPlainText() is "equivalent to" calling the example edit->textCursor().insertText(text).

Re: Documentation issue

Posted: Thu Sep 10 2020 12:49 am
by seasoned_geek
Okay, I looked again. You are correct. Kind of dangerous with things like that though. Lots of people do what I did and "just look for the code."

Re: Documentation issue

Posted: Thu Sep 10 2020 10:34 pm
by barbara

Code: Select all

Kind of dangerous   . . .  Lots of people do what I did 
It is never a good idea to read only part of a method's documentation, you might misinterpret something. As you later noted, our sample code is correct and there is nothing wrong with this documentation. This was actually good sample code.

There are numerous places in our API docs which say that calling the current method is equivalent to calling some other method. We also might note calling the current method is not advisable under some conditions, this is important information. Other times we need to indicate the current method returns a temporary and for more information refer to the indicated link.

My point is that as developers we are responsible for reading the documentation and not skipping over parts, it is all relevant. When we read docs and it seems like their may be an issue or we do not understand some portion then we should go back and read it very carefully. Our team continuously reads the docs to ensure they are accurate, clear to read, and use the current C++ terminology. If we do miss the mark please feel free to help us improve the documentation.

Barbara