[PATCH] authz: document missorted function in specfile

[Alexandre Julliard]

Nikolay Sivov <bunglehead at gmail.com> writes:

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

I still don't think it's surprising enough to warrant a comment. Sorting
is not a strict rule, and having unsorted functions should not be
considered unexpected.

-- 
Alexandre Julliard
julliard at winehq.org