Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: TOC items order issue #10585

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Conversation

filzrev
Copy link
Contributor

@filzrev filzrev commented Mar 11, 2025

This PR intended to fix issue #10332

Background
When using Globalization Invariant Mode. string is sorted with ordinal orders.
And it will cause some order problems, which seems not to be natural orders.

What's changed in this PR

1. Add SymbolStringComparer.cs

Add custom StringComparer that sort ASCII chars.
It's similar to StringComparer.InvariantCulture's order but have following differences.

  • Non ASCII chars are sorted with ordinal order.
  • Non-printable chars are compared. (built-in string comparer seems ignoring these chars)
  • Char orders of ',' and ')' are inverted. (To handle .NET overloaded method parameter orders)

2. Modify YamlViewModelExtensions.cs

Modify toc /enum items sort logics to use custom SymbolStringComparer.

3. Add test class to that contains test for Issue10332

Confirmed generated web site symbols are ordered as expected.
And enumSortOrder:alphabetic behavior is confirmed by modifying seed/docfx.json manually.

Additional apply formatter to Class1.cs file content.

4. Update snapshot files with snapshot.yml

@filzrev filzrev force-pushed the fix-toc-orders-issue branch from 48923d1 to e4e8b92 Compare March 11, 2025 04:04
/// (e.g. StringComparer.InvariantCulture.Compare("\x0000 ZZZ \x0000"," ZZZ ")) returns 0).
/// This feature is not implement by this comparer.
/// </remarks>
internal sealed class SymbolStringComparer : IComparer<string>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems to be occurred when using "outputFormat": "mref" options.
When using apiPage or markdown options. It works as expected.

The apiPage output does not use a custom string comparer and seems to sort by name directly, does it work to sort by name also for mref output?

Copy link
Contributor Author

@filzrev filzrev Mar 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ApiPage resolve names with SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp)
So name is represented as followings.

Class1
Class1.IRoutedView
Class1.IRoutedView<T>
Class1.IRoutedViewModel
Class1.IRoutedViewModelBase

So generics are sorted as expected when it's sorted by ordinal .
Because < char code is smaller than alphabet char.

On the other hand, when using Mref output format.
name is represented as followings.

BuildFromProject.Class1
BuildFromProject.Class1.IRoutedView
BuildFromProject.Class1.IRoutedViewModel
BuildFromProject.Class1.IRoutedViewModelBase
BuildFromProject.Class1.IRoutedView`1

So it requires SymbolStringComparer to get expected results.
I thought SymbolStringComparer should be also applied to ApiPage/Markdown output format.

@filzrev filzrev force-pushed the fix-toc-orders-issue branch from eb07ed7 to 42e8d00 Compare March 28, 2025 07:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants