sort-members should only apply to class members

[alandefreitas]

The sort-members should only be applied to class members. The documention says it also sorts the members of namespaces:

Sort the members of a record or namespace

I think part of the confusion was because doxygen also sorts the members of files with the analogous option:

If the SORT_MEMBER_DOCS tag is set to YES then Doxygen will sort the (detailed) documentation of file and class members alphabetically by member name. If set to NO, the members will appear in declaration order.

https://www.doxygen.nl/manual/config.html#cfg_sort_member_docs

[jll63]

I surmise that this "bug" is actually an accidental feature, and it should not be "fixed".

Alphabetical ordering is perfect for indexes. For namespaces, it is completely arbitrary, because it puts cleanup before setup, finalize before initialize, DiagonalMatrix before Matrix, SquareMatrix and SymmetricMatrix. It mixes frequently used symbols with those "for advanced use" .

As of version 0.04, it is possible to order symbols on namespace doc pages using forward declarations, possibly in a #ifdef __MRDOCS__ block. For example:

class Matrix;
class SquareMatrix;
class SymmetricMatrix;
class DiagonalMatrix;

void initialize();
void finalize();

If mrdocs sees these before the actual definitions, wherever they are, it appears to respect their order.

I understand that namespace ordering presents a challenge. While aggregate members appear in the same order in every translation unit (or else you probably have ODR violations), namespaces are open. Symbols can appear, or not, in different translation units, and in different orders, depending on the order of header inclusion. However, in mrdocs context, there is only one TU, and the author controls its content (see for example Boost.URL). Even if we need to feed multiple TUs to mrdocs, it is easy to arrange for the library's header to always include a header with forward declarations (possibly, again, in a conditional block).

By the way - typedefs are listed, in the Types section, after aggregates proper. Even if sorting is enabled. That is a bug IMO. Maybe typedefs should get their own section?

In the longer run, we could consider adding a section in mrdocs.yml with a (possibly non exhaustive) list of namespace-scoped symbols, and honor the list's order. In the meantime, I suggest we leave the current behavior as is; or, if it seems important to be able to ab-sort namespace symbols, but not aggregate symbols, we could have separate sort-members and sort-namespaces settings. That is probably easy to implement.

[alandefreitas]

I understand that namespace ordering presents a challenge.

It sounds more like an impossibility than a challenge. The order of members would be changing arbitrarily, as the order in which TU are processed changes arbitrarily.

However, in mrdocs context, there is only one TU

Not really. MrDocs supports as many TU as we want.

I get the point that the user can force a single TU in his project, but we still have to know what to do about the general case.

Even if we need to feed multiple TUs to mrdocs, it is easy to arrange for the library's header to always include a header with forward declarations (possibly, again, in a conditional block).

It's possible, but I don't want to tell users they have to do that if they want a non-arbitrary order.

we could have separate sort-members and sort-namespaces settings

We can do that. The problem is defining the behavior for the general case when sort-namespaces is false

[jll63]

We can do that. The problem is defining the behavior for the general case when sort-namespaces is false

What about scanning TUs from top to bottom, and from left to right. Index is set at the first occurrence of a symbol. For example:

a.cpp	b.cpp	c.cpp	d.cpp
class a;	class a;	class d;	class g;
class b;	class c;	class a;
class e;
class f;

yields: a b e f c d g

Hmmm, it appears that cppreference.com documents namespaces as direct indexes, for example std and std::pmr. By direct I mean that it does not group symbols in categories (although it does mark functions with () and templates with <>). Yet it puts macros and exposition-only symbols in separate indexes. It does not have a problem with overloads (e.g. transform), because cppreference places them on the same page, unlike MrDocs.

[alandefreitas]

That's not the problem. The problem is the a.cpp, b.cpp, c.cpp, d.cpp would be in an arbitrary order. We could force some order at the end, but this would be more like sorting by a different criterion rather than not sorting. I was actually going to include another option for other sorting criteria in MrDocs. But this is very low priority at the moment.