The "Function Notes"

[mr-es335]

Good day,

Regarding the information provided in the HelpFile - I have the following two questions, the first with regards to "audience relevance" and the second, with regards to "Functions".

Question 1: What is the intended audience for the employment of the HelpFile?

Question 2: What are the responses to the following two queries?
• 1) "When an optional parameter needs to be defined and is preceded by one or more optional parameters, the default value must be given for that parameter. Generally speaking functions should accept the Default keyword when you wish to use the default parameter."
• Question: What is "that parameter" in reference to...is it the "optional parameter" or is it the "one or more optional parameters"?

2) What is the following statement inferring|referring to?
• "If a function uses the @error flag method, the flag should be checked immediately after the function returns, as the @error flag will be reset to 0 when entering the next function. No attempt to use or access the function return value should be made if the @error flag has been set as in that case the return value is generally undefined..."
• This statement makes absolutely no sense to me whatsoever!

In any form of technical writing, I have adhered to three important principles, 1) non-assumptiveness, 2) non-pronoun employment, and 3) non-contraction employment.
1) non-assumptiveness: Never, ever assume the knowledge of of the intelligence of the audience.
2) non-pronoun employment: Never employ the use of pronouns.
• For example: "Among other things, that means you can assign a function to a variable, pass it around as an argument..." "Pass it around..." should be "Pass that function around..."
3) non-contraction employment: "can't" should be "cannot", "don't - "do not"...and so on.

Anyhow, answers to the above two questions would be greatly appreciated!

[Melba23]

mr-es335,

Ans 1: The coders who use AutoIt.

Ans 2.1: It refers to the preceding optional parameter(s).

Ans 2.2: Functions return a value (which might be as simple as 1/0 indicating success/failure, but could be an array or other complex variable) and the at the same time set the @error flag to 0 (success) or a non-zero value (usually indicating failure mode). If the @error flag is set, then the return value of the function could be anything at all and so should not be used.

Clearer?

As to your 3 comments:

1. We have been complimented on the content and clarity of our help file, but there sometimes those who find it too complex......

2 & 3: See this quote.

M23