Documentation Suggestion Box
-
Often times when developing some project, a weakness or omission is uncovered in the documentation for a given class. Typically, I try to Google for an answer but usually I wind up using trial and error to fill in such holes. Once such answers are ferreted out, it would be the considerate thing to share the newly discovered information with others. At the present time there is no straightforward means to get the documentation updated to include these omissions (or sometimes even outright mistakes). You can share the info in a forum (like here) but that can be hit or miss for someone else looking for the information. My idea would be to have a suggestion box where such things could be posted, and where documentation maintainers could go to discover holes in the documentation. Here's an example of a documentation hole and suggestion:
In the docs for the QString class, the "toDouble(bool * ok)" function is described more or less as follows:
Returns the string converted to a double value; Returns 0.0 if the conversion fails.
If a conversion error occurs, *ok is set to false; otherwise *ok is set to true.
Various string formats for floating point numbers can be converted to double values
(Plus several examples and additional inormation)This is fine as far as it goes. The problem is what is NOT in the documentation - Specifically what conditions cause an error and fail to convert into a double. In point of fact, the user has to write a small program and test failure modes. For example, a program with a single QLineEdit whose text is analyzed after any change and which reports the state of "ok" and the value of the converted number. Then, after trying every possible combination of numbers and text one can think of, construct a set of rules.
It turns out that "toDouble(bool* ok) will fail if there are any extraneous characters in the QString. The number must contain only an optional sign, digits, a decimal point if needed, an optional exponent for scientific notation, which can be either g, G, e or E, the exponent's sign and an integer exponent. The presence of virtually any other characters (except space) will cause failure. For example, attempting to add a UNIT to a number (as in 100 V) will fail.
Even the addition of a simple phrase like: "the QString may contain ONLY a valid number. No additional characters are permitted." would save the programmer several hours of testing, searching and reading of desultory posts on various forums*
*There's another suggestion in there somewhere! When someone asks "What characters are legal in a QString toDouble conversion", DON'T answer with something like "Why are you using a QString for that?" Answer the question asked and if you don't know the answer keep quiet. But, alas, that's for a different post
-
You can file a bug report for every missing piece of information you find in the documentation. If you have the time and willpower, you can also submit the patch yourself at the same time - this way it will arrive to a new Qt version sooner :)
-
Hi, welcome to devnet.
Any bugs or suggestions should be reported "here":http://bugreports.qt-project.org (with a Documentation label). Posting this on a forum will have little to none attention from the devs.
In the meantime you can scroll to the bottom of the doc page. There's a community comments section there. Share your findings with others.
Sometimes it's good to question the question :) For example if someone asks what will be a result of some undefined behavior you could answer 42, but it's actually more beneficial to explain why he/she shouldn't be doing it in the first place.
If you're getting a lot of answers like that maybe you formulate your questions wrong, ie. in a way suggesting you want to do something that is considered wrong. Giving some context to your questions is always a good thing.
-
Chris:
Thanks for the Welcome! - and the thoughtful reply. I'll have a look at the bug-reports, but the idea of a formal suggestion box does have the advantage of allowinng for a broader range of input. And, while I agree that it's good to question the question (I do this myself), I am intending to refer to well formed questions. Both of your examples are right on the money in terms of pointing the questioner in a potentially more fruitful direction. For example, I discovered that strtod is a much better solution for my problem, since it converts the first number it finds and the returns a pointer to the stuff that follows which can then be used to decode any numeric suffix (i.e. MicroSiemens, etc). But, before I got there, I still wanted to know what is legal in the toDouble conversion - hence the suggestion box idea. And really, it's not so much that I'm getting so many answers like the one I criticised, but that when searching about, I find a lot of answers to other people's posts that look like that. In fact, I'm a little embarassed that I mentioned it at all since I fear that it will become somewhat of a red-herring and detract from the real intent of my post. -
I'm not saying suggestion box is a bad idea. It's just that there is the bugreports site, official blog, mailing lists, IRC channels and this forum. I don't think adding another place for tracking stuff to the mix is beneficial at all.
And don't let the name fool you. Bugreports site is not only for bugs. It tracks ideas and features too. It has labeling, categorization and even voting buttons to track hot issues. It's open to anyone and moderated by the actual devs so it's hard to get any closer to the issues. It's basically your suggestion box and more.
