Documentation issue

Post Reply
seasoned_geek
Posts: 61
Joined: Thu Jun 11 2020 12:18 pm

Documentation issue

Post 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.

barbara
Posts: 201
Joined: Sat Apr 04 2015 2:32 am

Re: Documentation issue

Post 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).

seasoned_geek
Posts: 61
Joined: Thu Jun 11 2020 12:18 pm

Re: Documentation issue

Post 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."

barbara
Posts: 201
Joined: Sat Apr 04 2015 2:32 am

Re: Documentation issue

Post 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

Post Reply