Clarify negative -1 return value for sscanf/fscanf

[jordikroon]

Also did some maintenance work for these files.
See commits in order. Specifically this commit 7af7c98 is what it's all about.

Ref: https://externals.io/message/131005

[hakre]

@jordikroon thanks for the initiative, I spotted the mixed forms of "were" and "are" (time /E: Active Voice) across the paragraphs. I have to admit that I don't know which rule we apply/use specifically, probably present is better because it is more active, less passive language (for which IIRC [and as I remembered incorrectly] we have [not] a rule in the docs folder), but as English is not my first language I might be a bit off here, so please take it with a grain of salt. This btw. is across the two functions' files, and was already different previously.

/E: And my concrete line comments didn't make it to the server and then back.

[jordikroon]

@hakre you bring up a good and important point. Present tense feels more natural in the documentation. However, this has not always been consistent across the existing files, so I think it would be good to standardize on one style going forward. Thank you for bringing this up. Perhaps it would be good to mark this more explicitly in the style guide. Since it contributes to a professional documentation.

[hakre]

@jordikroon Thank for your thoughful feedback and considering my thoughts. I've taken it as an opportunity to scan the doc-base/docs folder once more (phpdoc doc-base docs in one of my forks), specifically the Style guidelines in the file entry named style.md.

A General Grammar HTML section exists, but it does not contain a hint of Active Voice as I think this is named more appropriately (not past / present tense as the word time may have suggested in my earlier comment).

Prolonging too much on this could derail yours beautiful PR a bit, so it should go without writing, that I would not suggest to water it down with this discussion too much, just from what I know it is normally suggested to use active, not passive, voice for documentation and the already existing sentence bullet-pointed in the General Grammar section may hint towards that:

If a statement includes a conditional conjunction, the condition being met should come before the independent clause.

Conditions are normally formulated in active voice I'd say (probably what "conditional conjunction" pins down in that sentence), but this sentence is only what caught my eye while scanning.

And I spared the Personalization section that is more leading but may only be contextually related.

Henceforth, I'm thinking that your suggestion to align ("standardize") it within your PR's changed XML fragments in the *scanf() function family, e.g. to "are" not "were", could be a good example - if you feel that's right for your changes. Doing so may also help us to find a useful guideline for our future edits.

[hakre]

@jordikroon okay, I stand corrected after consulting more resources, incl. grammatical onces: my earlier time was more correct (tense is different), but this is not active or passive voice as I had it in mind (which could also be a rule for a style-guide, but it's not what caught my eyes). Both the "were" and "are" that I spotted are passive constructions. Even if a style-guide would have a rule for active voice to prefer (which it doesn't), this is not a binary preference. E.g. if the focus is on the return value, passive voice can put that on focus, not the actor (e.g. the caller of a function - as we can't use "you" per style-guide :D).

So this is not easy to find some rule-of thumb that helps editing/reviewing I guess and "are" and "were" are not in a real "conflict" within the same simpara as I now understand it.

[jordikroon]

Thank you all for checking. I must say this escalated quickly (in a good sense). While I was very focused on fixing the initial issue. I didn't expect those 3 functions to be so similar yet historically so wrongfully implemented.

That said it's good to see that corrected as well.

I will leave it open for a few days, so if anyone has any additional notes. Please drop those here.