[PATCH] authz: document missorted function in specfile

[Austin English]

On Tue, May 23, 2017 at 4:11 AM, Alexandre Julliard <julliard at winehq.org> wrote:
> Austin English <austinenglish at gmail.com> writes:
>
>> Signed-off-by: Austin English <austinenglish at gmail.com>
>> ---
>>  dlls/authz/authz.spec | 2 ++
>>  1 file changed, 2 insertions(+)
>>
>> diff --git a/dlls/authz/authz.spec b/dlls/authz/authz.spec
>> index eb9e044d2a..1e9edefc59 100644
>> --- a/dlls/authz/authz.spec
>> +++ b/dlls/authz/authz.spec
>> @@ -35,6 +35,8 @@
>>  @ stub AuthziInitializeAuditQueue
>>  @ stub AuthziInitializeContextFromSid
>>  @ stub AuthziLogAuditEvent
>> +# AuthziModifyAuditEvent2 comes before AuthziModifyAuditEvent on native,
>> +# even though AuthzInitializeObjectAccessAuditEvent is before AuthzInitializeObjectAccessAuditEvent2
>>  @ stub AuthziModifyAuditEvent2
>>  @ stub AuthziModifyAuditEvent
>>  @ stub AuthziModifyAuditEventType
>
> There are many functions that aren't sorted, I don't think this warrants
> a comment. If you have a script for this, you may want to maintain a
> list of exceptions inside the script instead.

I have to disagree. My plan is to find the functions that actually
ordinals, and label them as such (i.e., @ stub foo -> 1 stub foo). We
already have several other comments of dubious value, I'd argue this
is just as helpful, if not more helpful that something like:
https://source.winehq.org/git/wine.git/blob/HEAD:/dlls/setupapi/setupapi.spec#l240

The comment helps future readers understand why the sorting rules
apply one way in one place, but the complete opposite in another. It's
completely non-obvious which sorting mistakes are developer error, and
which are Microsoft error and IMO should be documented. Keep in mind
that not every developer has access to a windows machine (Testbot
excluded), and may not be easily able to run winedump on some windows
dlls.

Yes, I do have a script for sorting but I don't have an easy way to
filter out based on which functions to sort and not sort, it would
exclude an entire specfile.

FWIW, a quick look for the win10, 32-bit dlls shows that of 2005
windows dlls in the root directory, 536 don't follow the expected
sorting rules. Of those, 476 appear to contain ordinals (first line
doesn't match after sorting). That leaves approximately 60 files that
appear to solely have missorted function names (files with ordinals
may also contain sorting differences). And most of those don't exist
in wine (133 are in wine, 343 aren't). I didn't verify how many are
wine bugs versus windows bugs, but in any case, it's not an
overwhelming number.

While the number of comments will definitely be greater than 1, I
still feel that they have value to developers and the wider community.
If churn is the issue, I could save that change for last, and send
them all in one commit, would that be preferable?

-
-Austin
GPG: 14FB D7EA A041 937B