Sort equal weighted "Mentioned In" articles alphabetically (#1221)

If articles have same # of mentions, sort them alphabetically.

Resolves: rdar://150870055

Author: mportiz08

Sources/SwiftDocC/Semantics/Article/ArticleSymbolMentions.swift

@@ -32,7 +32,14 @@ struct ArticleSymbolMentions {
         // Mentions are sorted on demand based on the number of mentions.
         // This could change in the future.
         return mentions[symbol, default: [:]].sorted {
-            $0.value > $1.value
+            // If a pair of articles have the same number of mentions, sort
+            // them alphabetically.
+            if $0.value == $1.value {
+                return $0.key.description < $1.key.description
+            }
+
+            // Otherwise, sort articles with more mentions first.
+            return $0.value > $1.value
         }
         .map { $0.key }
     }

Tests/SwiftDocCTests/Semantics/ArticleSymbolMentionsTests.swift

@@ -36,6 +36,56 @@ class ArticleSymbolMentionsTests: XCTestCase {
         XCTAssertEqual(gottenArticle, article)
     }
 
+    // Test the sorting of articles mentioning a given symbol
+    func testArticlesMentioningSorting() throws {
+        let bundleID: DocumentationBundle.Identifier = "org.swift.test"
+        let articles = ["a", "b", "c", "d", "e", "f"].map { letter in
+            ResolvedTopicReference(
+                bundleID: bundleID,
+                path: "/\(letter)",
+                sourceLanguage: .swift
+            )
+        }
+        let symbol = ResolvedTopicReference(
+            bundleID: bundleID,
+            path: "/z",
+            sourceLanguage: .swift
+        )
+
+        var mentions = ArticleSymbolMentions()
+        XCTAssertTrue(mentions.articlesMentioning(symbol).isEmpty)
+
+        // test that mentioning articles are sorted by weight
+        mentions.article(articles[0], didMention: symbol, weight: 10)
+        mentions.article(articles[1], didMention: symbol, weight: 42)
+        mentions.article(articles[2], didMention: symbol, weight: 1)
+        mentions.article(articles[3], didMention: symbol, weight: 14)
+        mentions.article(articles[4], didMention: symbol, weight: 2)
+        mentions.article(articles[5], didMention: symbol, weight: 6)
+        XCTAssertEqual(mentions.articlesMentioning(symbol), [
+            articles[1],
+            articles[3],
+            articles[0],
+            articles[5],
+            articles[4],
+            articles[2],
+        ])
+
+        // test that mentioning articles w/ same weights are sorted alphabetically
+        //
+        // note: this test is done multiple times with a shuffled list to ensure
+        // that it isn't just passing by pure chance due to the unpredictable
+        // order of Swift dictionaries
+        for _ in 1...10 {
+            mentions = ArticleSymbolMentions()
+            XCTAssertTrue(mentions.articlesMentioning(symbol).isEmpty)
+            for article in articles.shuffled() {
+                mentions.article(article, didMention: symbol, weight: 1)
+            }
+            XCTAssertEqual(mentions.articlesMentioning(symbol), articles)
+        }
+    }
+
     func testSymbolLinkCollectorEnabled() throws {
         let (bundle, context) = try createMentionedInTestBundle()