[PATCH] authz: document missorted function in specfile

[Nikolay Sivov]

On 24.05.2017 9:50, Austin English wrote:
> 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.

For modules with "unexpected" order you can have a comment on top of
spec file, mentioning that this file is sorted as it should be. That is
if you want comment at all, comments in the middle look like noise to me.

> 
> 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
> 
>