QLineEdit's inputMask property is documented unclearly/incorrectly/incompletely

As there are numerous issues in the documentation of QLineEdit's inputMask property, this ticket reports several bugs and other issues. Feel free to mark this as resolved even if some of these issues may not be; I will open another ticket if necessary.

I thank ddubya from freenode's #qt, who helped me develop a good understanding of inputMask and validate some of the issues reported here. That being said, I may have misunderstood parts of how inputMask works - apologies in advance if some of the following is wrong.

Beginning

The documentation starts with:

This property holds the validation input mask

If no mask is set, inputMask() returns an empty string.

Sets the QLineEdit's validation mask. Validators can be used instead of, or in conjunction with masks; see setValidator().

Unset the mask and return to normal QLineEdit operation by passing an empty string ("").

The first sentence is missing a period (".") at the end. The second and fourth paragraph should probably be merged.

The Big Issues

The worst part is as follows (I added violet):

The table below shows the characters that can be used in an input mask. A space character, the default character for a blank, is needed for cases where a character is permitted but not required.
 
 
[table]
The mask consists of a string of mask characters and separators, optionally followed by a semicolon and the character used for blanks. The blank characters are always removed from the text after editing.

There are several issues here:

1. The first sentence is wrong. Any character can be used in an input mask (hopefully).
2. The second sentence refers to blanks, even though qlineedit.html does not define what blanks are anywhere.
3. That same sentence is extremely misleading if I understand correctly; blanks are used where a character is permitted, whether or not it is required.
4. If "D" excludes "0", that should be indicated explicitly.
5. The backslash entry assumes the reader is experienced and should be rewritten in a formal way, explaining that it affects the treatment of the following character (keeping in mind that there may be none).
6. The sentence immediately after the table refers to separators, even though qlineedit.html does not define what separators are anywhere.
7. That same sentence should refer to "special characters" rather than "mask characters".
8. That same sentence becomes mostly meaningless if separators are all characters which aren't special; only the last part should be rephrased and kept.
9. The parts treating blanks (which I put in violet) should be together, not splitted by a big table.

I believe this should start with an explanation of what an input mask is and how it helps. Wikipedia's article compares masks to templates. I also suggest using a simple example described in-depth. This could be a mask to enter a number of seconds taken to run a 100 meters sprint, using mask "99;". It can explain that if the user types letter "f", nothing happens. If the user types "0", the first underscore is replaced by a "0" and the cursor moves to the second position. It could then treat pattern "99.99;", to keep more precise timings, introducing the "separators" concept.

In terms of terminology:

1. I recommend to use "literal character" instead of "separator", since these characters do not necessarily separate input characters (for example, in pattern "(999) 000-0000", the first parenthesis does not separate anything).
2. The "blank" character could be called the "placeholder" character too.

The blank can be defined as the character:

• which is used to fill the initial input string, in the positions where users can input a character.
• which can be entered in positions which take an optional character
• of which any occurrence is removed from the input string's value at the end of the field's edition (as already explained)

End

There are several issues with the examples:

1. The IP address example only applies to IP version 4 addresses - the description should specify that.
2. In the last example (license numbers), blanks should be spaces if I understand correctly, not the minus sign as the notes claim.
3. The "license numbers" mask corresponds to license keys which would consist in letters, not numbers.
4. The "license numbers" example probably refers to software licenses. It would be clearer if it was described as a "Software license key" pattern. That being said, there are so many patterns possible for that, that I'm not sure such an example is helpful. If it's kept, please provide an example of a corresponding input.
5. "blanks are space" and such should rather read "the blank character is the space character".
6. Some of these masks are insufficient for fully validating. It would be best to specify that the IP address and ISO date patterns are not sufficient for that.

The documentation ends with "To get range control (e.g., for an IP address) use masks together with validators."
I find that sentence unclear - please remove or clarify it (I am not sure what it means and how it would be clarified).