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.

Sign up for GitHub

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

docgen: sort symbols (fix #17910) #18560

Merged
merged 5 commits into from
Jul 25, 2021
Merged

docgen: sort symbols (fix #17910) #18560

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c24e61b
docgen: sort symbols (fix #17910)
a-mr Jul 22, 2021
208862a
add workaround + change naming
a-mr Jul 22, 2021
cfdd633
switch to a dedicated sort comparator
a-mr Jul 24, 2021
11f1bb6
fix numbers with unequal string lengths
a-mr Jul 25, 2021
76599e8
dedicated `sortName` instead of `plainNameEsc`:
a-mr Jul 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 43 additions & 3 deletions compiler/docgen.nim
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,46 @@ type
proc add(dest: var ItemPre, rst: PRstNode) = dest.add ItemFragment(isRst: true, rst: rst)
proc add(dest: var ItemPre, str: string) = dest.add ItemFragment(isRst: false, str: str)

proc cmpDecimalsIgnoreCase(a, b: string): int =
## For sorting with correct handling of cases like 'uint8' and 'uint16'.
## Also handles leading zeroes well.
runnableExamples:
doAssert cmpDecimalsIgnoreCase("uint8", "uint16") < 0
Copy link
Member

@timotheecour timotheecour Jul 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

what about foo08 vs foo8?
right now it gives 0, which is not intuitive because the strings are not equal.
how about instead considering 08 is longer than 8 and having:

doAssert cmpDecimalsIgnoreCase("ab8", "ab08") < 0
doAssert cmpDecimalsIgnoreCase("ab8de", "ab08c") < 0 # sanity check

Copy link
Contributor Author

Choose a reason for hiding this comment

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

agree, fixed.

doAssert cmpDecimalsIgnoreCase("val00032", "val16suffix") > 0
doAssert cmpDecimalsIgnoreCase("val16suffix", "val16") > 0
doAssert cmpDecimalsIgnoreCase("val_08_32", "val_08_8") > 0
doAssert cmpDecimalsIgnoreCase("val_07_32", "val_08_8") < 0
let aLen = a.len
let bLen = b.len
var
iA = 0
iB = 0
while iA < aLen and iB < bLen:
if isDigit(a[iA]) and isDigit(b[iB]):
var
limitA = iA
limitB = iB
while limitA < aLen and isDigit(a[limitA]): inc limitA
while limitB < bLen and isDigit(b[limitB]): inc limitB
var pos = max(limitA-iA, limitB-iA)
while pos > 0:
if limitA-pos < iA: # digit in `a` is 0 effectively
result = ord('0') - ord(b[limitB-pos])
elif limitB-pos < iB: # digit in `b` is 0 effectively
result = ord(a[limitA-pos]) - ord('0')
else:
result = ord(a[limitA-pos]) - ord(b[limitB-pos])
if result != 0: return
dec pos
iA = limitA
iB = limitB
else:
result = ord(toLowerAscii(a[iA])) - ord(toLowerAscii(b[iB]))
if result != 0: return
inc iA
inc iB
result = (aLen - iA) - (bLen - iB)

proc prettyString(a: object): string =
# xxx pending std/prettyprint refs https://github.com/nim-lang/RFCs/issues/203#issuecomment-602534906
for k, v in fieldPairs(a):
Expand Down Expand Up @@ -1158,7 +1198,7 @@ proc finishGenerateDoc*(d: var PDoc) =
var resolved = resolveSubs(d.sharedState, f.rst)
renderRstToOut(d[], resolved, result)
of false: result &= f.str
proc cmp(x, y: Item): int = cmpIgnoreCase(x.sortName, y.sortName)
proc cmp(x, y: Item): int = cmpDecimalsIgnoreCase(x.sortName, y.sortName)
for k in TSymKind:
for item in d.section[k].secItems.sorted(cmp):
var itemDesc: string
Expand Down Expand Up @@ -1278,10 +1318,10 @@ proc genSection(d: PDoc, kind: TSymKind, groupedToc = false) =
"sectionid", $ord(kind), "sectionTitle", title,
"sectionTitleID", $(ord(kind) + 50), "content", d.section[kind].finalMarkup]

proc cmp(x, y: TocItem): int = cmpIgnoreCase(x.sortName, y.sortName)
proc cmp(x, y: TocItem): int = cmpDecimalsIgnoreCase(x.sortName, y.sortName)
if groupedToc:
let overloadableNames = toSeq(keys(d.tocTable[kind]))
for plainName in overloadableNames.sorted():
for plainName in overloadableNames.sorted(cmpDecimalsIgnoreCase):
var overloadChoices = d.tocTable[kind][plainName]
overloadChoices.sort(cmp)
var content: string
Expand Down
164 changes: 82 additions & 82 deletions nimdoc/testproject/expected/testproject.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,31 +244,6 @@ <h1 class="title">testproject</h1>
<li><a class="reference" href="#z1"
title="z1(): Foo">z1(): Foo</a></li>

</ul>
<ul class="simple nested-toc-section">z10
<li><a class="reference" href="#z10"
title="z10()">z10()</a></li>

</ul>
<ul class="simple nested-toc-section">z11
<li><a class="reference" href="#z11"
title="z11()">z11()</a></li>

</ul>
<ul class="simple nested-toc-section">z12
<li><a class="reference" href="#z12"
title="z12(): int">z12(): int</a></li>

</ul>
<ul class="simple nested-toc-section">z13
<li><a class="reference" href="#z13"
title="z13()">z13()</a></li>

</ul>
<ul class="simple nested-toc-section">z17
<li><a class="reference" href="#z17"
title="z17()">z17()</a></li>

</ul>
<ul class="simple nested-toc-section">z2
<li><a class="reference" href="#z2"
Expand Down Expand Up @@ -309,6 +284,31 @@ <h1 class="title">testproject</h1>
<li><a class="reference" href="#z9"
title="z9()">z9()</a></li>

</ul>
<ul class="simple nested-toc-section">z10
<li><a class="reference" href="#z10"
title="z10()">z10()</a></li>

</ul>
<ul class="simple nested-toc-section">z11
<li><a class="reference" href="#z11"
title="z11()">z11()</a></li>

</ul>
<ul class="simple nested-toc-section">z12
<li><a class="reference" href="#z12"
title="z12(): int">z12(): int</a></li>

</ul>
<ul class="simple nested-toc-section">z13
<li><a class="reference" href="#z13"
title="z13()">z13()</a></li>

</ul>
<ul class="simple nested-toc-section">z17
<li><a class="reference" href="#z17"
title="z17()">z17()</a></li>

</ul>

</ul>
Expand Down Expand Up @@ -398,6 +398,11 @@ <h1 class="title">testproject</h1>
<li><a class="reference" href="#testNimDocTrailingExample.t"
title="testNimDocTrailingExample()">testNimDocTrailingExample()</a></li>

</ul>
<ul class="simple nested-toc-section">z6t
<li><a class="reference" href="#z6t.t"
title="z6t(): int">z6t(): int</a></li>

</ul>
<ul class="simple nested-toc-section">z14
<li><a class="reference" href="#z14.t"
Expand All @@ -408,11 +413,6 @@ <h1 class="title">testproject</h1>
<li><a class="reference" href="#z15.t"
title="z15()">z15()</a></li>

</ul>
<ul class="simple nested-toc-section">z6t
<li><a class="reference" href="#z6t.t"
title="z6t(): int">z6t(): int</a></li>

</ul>

</ul>
Expand Down Expand Up @@ -768,51 +768,6 @@ <h1><a class="toc-backref" href="#12">Procs</a></h1>

cz1

</dd>
<a id="z10"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z10"><span class="Identifier">z10</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>


<p><strong class="examples_text">Example: cmd: -d:foobar</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>cz10

</dd>
<a id="z11"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z11"><span class="Identifier">z11</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>


<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>

</dd>
<a id="z12"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z12"><span class="Identifier">z12</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>


<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>

</dd>
<a id="z13"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z13"><span class="Identifier">z13</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>

cz13
<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span></pre>

</dd>
<a id="z17"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z17"><span class="Identifier">z17</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>

cz17 rest
<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>rest

</dd>
<a id="z2"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z2"><span class="Identifier">z2</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
Expand Down Expand Up @@ -873,6 +828,51 @@ <h1><a class="toc-backref" href="#12">Procs</a></h1>
<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Identifier">doAssert</span> <span class="DecNumber">1</span> <span class="Operator">+</span> <span class="DecNumber">1</span> <span class="Operator">==</span> <span class="DecNumber">2</span></pre>

</dd>
<a id="z10"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z10"><span class="Identifier">z10</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>


<p><strong class="examples_text">Example: cmd: -d:foobar</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>cz10

</dd>
<a id="z11"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z11"><span class="Identifier">z11</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>


<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>

</dd>
<a id="z12"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z12"><span class="Identifier">z12</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>


<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>

</dd>
<a id="z13"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z13"><span class="Identifier">z13</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>

cz13
<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span></pre>

</dd>
<a id="z17"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#z17"><span class="Identifier">z17</span></a><span class="Other">(</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
<dd>

cz17 rest
<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>rest

</dd>

</dl></div>
Expand Down Expand Up @@ -1014,6 +1014,13 @@ <h1><a class="toc-backref" href="#18">Templates</a></h1>
<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">2</span></pre>

</dd>
<a id="z6t.t"></a>
<dt><pre><span class="Keyword">template</span> <a href="#z6t.t"><span class="Identifier">z6t</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span></pre></dt>
<dd>

cz6t

</dd>
<a id="z14.t"></a>
<dt><pre><span class="Keyword">template</span> <a href="#z14.t"><span class="Identifier">z14</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
Expand All @@ -1040,13 +1047,6 @@ <h1><a class="toc-backref" href="#18">Templates</a></h1>
<p><strong class="examples_text">Example:</strong></p>
<pre class="listing"><span class="Keyword">discard</span> <span class="DecNumber">1</span></pre>in or out?

</dd>
<a id="z6t.t"></a>
<dt><pre><span class="Keyword">template</span> <a href="#z6t.t"><span class="Identifier">z6t</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span></pre></dt>
<dd>

cz6t

</dd>

</dl></div>
Expand Down