Skip to content

Conversation

@filzrev
Copy link
Contributor

@filzrev filzrev commented Jun 21, 2024

This PR intended to fix issue reported at #2532 (comment)

Details of problem

docfx metadata command failed with ArgumentException at this line

ArgumentException: An item with the same key has already been added. Key: Root.Datastore
  at bool TryInsert(TKey key, TValue value, InsertionBehavior behavior)
  at void Add(TKey key, TValue value)
  at MetadataItem GenerateNestedTocStructure(IEnumerable<KeyValuePair<string, MetadataItem>> namespaces,
     Dictionary<string, ReferenceItem> allReferences) in YamlMetadataResolver.cs:105

This problem is occurred when following conditions are met

  1. Referencing empty namespace with <see cref=""> tag.
  2. Using "namespaceLayout": "nested"
  3. Using "outputFormat": "mref"

What's changed in this PR

This PR changes allReferences.Add logic to allReferences.TryAdd method to skip when key already exists.

For example. When /// <see cref="Root.Datastore"/> comment exists.
allReferences contains this information as ReferenceItem (N:Root.Datastore).

Additionally I've added post-process logics to overwrite empty namespace reference.
It's required because Empty namespace don't generate HTML page.
So <see cref=""/> link is not works for empty namespace.

Test
I've manually tested following tests by using DocFxUndefinedReferenceBugDemo content.

  1. docfx metadata command successfully completed.
  2. <see cref="" link to empty namespace is rendered as plain text.
  3. <see cref="" link to other namespace is rendered as normal link.

@scott-ainsworth
Copy link

This branch correctly builds both the minimal sample I provided and the original 600+ *.cs files on which I first encountered the crash.

Thanks for the really fast resolution!

R/Scott Ainsworth

@yufeih yufeih added the bug-fix Makes the pull request to appear in "Bug Fixes" section of the next release note label Jun 25, 2024
Copy link
Contributor

@yufeih yufeih left a comment

Choose a reason for hiding this comment

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

Thank you @filzrev

@yufeih yufeih merged commit 2839361 into dotnet:main Jun 25, 2024
p-kostov pushed a commit to ErpNetDocs/docfx that referenced this pull request Jun 28, 2024
…ing empty namespace by doc comment (dotnet#10023)

fix: exception occurred when doc comment referencing empty namespace
renovate bot referenced this pull request in dotnet/dotnet-operator-sdk Jul 1, 2024
[![Mend
Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [docfx](https://togithub.com/dotnet/docfx) | `2.76.0` -> `2.77.0` |
[![age](https://developer.mend.io/api/mc/badges/age/nuget/docfx/2.77.0?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![adoption](https://developer.mend.io/api/mc/badges/adoption/nuget/docfx/2.77.0?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![passing](https://developer.mend.io/api/mc/badges/compatibility/nuget/docfx/2.76.0/2.77.0?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![confidence](https://developer.mend.io/api/mc/badges/confidence/nuget/docfx/2.76.0/2.77.0?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|

---

### Release Notes

<details>
<summary>dotnet/docfx (docfx)</summary>

### [`v2.77.0`](https://togithub.com/dotnet/docfx/releases/tag/v2.77.0)

<!-- Release notes generated using configuration in .github/release.yml
at main -->

#### What's Changed

##### 💥 Breaking Changes

- chore: Drop .NET 7 SDK supports by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9911](https://togithub.com/dotnet/docfx/pull/9911)

##### 🎉 New Features

- feat: Enable PreferCSSPageSize option for PDF generation by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9850](https://togithub.com/dotnet/docfx/pull/9850)
- feat: Add docfx JSON Schema files and related tests by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9852](https://togithub.com/dotnet/docfx/pull/9852)
- feat: Add `toc.json` transform logics using `toc.extension.js` by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9953](https://togithub.com/dotnet/docfx/pull/9953)
- feat: Better error when link not found by
[@&#8203;Patrick8639](https://togithub.com/Patrick8639) in
[https://github.com/dotnet/docfx/pull/9957](https://togithub.com/dotnet/docfx/pull/9957)
- feat: Add `categoryLayout` option for metadata generation by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9965](https://togithub.com/dotnet/docfx/pull/9965)
- feat: Permits to specify the placement of overwrites by
[@&#8203;Patrick8639](https://togithub.com/Patrick8639) in
[https://github.com/dotnet/docfx/pull/9937](https://togithub.com/dotnet/docfx/pull/9937)
- feat: Support private symbols by
[@&#8203;Patrick8639](https://togithub.com/Patrick8639) in
[https://github.com/dotnet/docfx/pull/9972](https://togithub.com/dotnet/docfx/pull/9972)
- feat: Add support for gzipped xrefmap that stored as local file by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9966](https://togithub.com/dotnet/docfx/pull/9966)
- feat: Enable view transitions feature by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9909](https://togithub.com/dotnet/docfx/pull/9909)

##### 🐞 Bug Fixes

- fix: PDF `Producer` document information by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9851](https://togithub.com/dotnet/docfx/pull/9851)
- fix: Xrefmap baseUrl problem reported at
[#&#8203;9866](https://togithub.com/dotnet/docfx/issues/9866) by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9869](https://togithub.com/dotnet/docfx/pull/9869)
- fix: Xref links are not resolved on docs site by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9880](https://togithub.com/dotnet/docfx/pull/9880)
- fix: Change same URL check logic to case invariant by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9883](https://togithub.com/dotnet/docfx/pull/9883)
- fix: Improve unresolved xref messages by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9884](https://togithub.com/dotnet/docfx/pull/9884)
- fix: Fix nightly build errors by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9913](https://togithub.com/dotnet/docfx/pull/9913)
- fix: TOC filter value is not shared between pages by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9912](https://togithub.com/dotnet/docfx/pull/9912)
- fix: Build problems when running .NET 6 version of docfx on some
environment by [@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9922](https://togithub.com/dotnet/docfx/pull/9922)
- fix: `docfx metadata` command throw `ArgumentException` when
referencing empty namespace by doc comment by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/10023](https://togithub.com/dotnet/docfx/pull/10023)
- fix: serve url link by
[@&#8203;WeihanLi](https://togithub.com/WeihanLi) in
[https://github.com/dotnet/docfx/pull/10035](https://togithub.com/dotnet/docfx/pull/10035)

##### 🚀 Performance Improvements

- perf: Change serializer for XrefMap from NewtonsoftJson to
System.Text.Json by [@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9872](https://togithub.com/dotnet/docfx/pull/9872)
- perf: Remove some enum boxing in GlobMatcher by
[@&#8203;lahma](https://togithub.com/lahma) in
[https://github.com/dotnet/docfx/pull/10051](https://togithub.com/dotnet/docfx/pull/10051)
- perf: Optimize CountWordInText by
[@&#8203;lahma](https://togithub.com/lahma) in
[https://github.com/dotnet/docfx/pull/10050](https://togithub.com/dotnet/docfx/pull/10050)

##### 🔧 Engineering

- chore: Skip unstable SVG content check that returned from PlantUML
Online Server by [@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9858](https://togithub.com/dotnet/docfx/pull/9858)
- deps: Update Spectre.Console package versions by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9894](https://togithub.com/dotnet/docfx/pull/9894)
- chore: fix NU5129 warning on `dotnet pack` command by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9942](https://togithub.com/dotnet/docfx/pull/9942)
- chore: Add PolySharp libarary to use latest C# syntax by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9960](https://togithub.com/dotnet/docfx/pull/9960)
- chore: Add snapshot update workflow by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9969](https://togithub.com/dotnet/docfx/pull/9969)
- chore: Remove unused workflow settings by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/10030](https://togithub.com/dotnet/docfx/pull/10030)

##### 📄 Documentation

- docs: Fix typo by
[@&#8203;carlos-regis](https://togithub.com/carlos-regis) in
[https://github.com/dotnet/docfx/pull/9871](https://togithub.com/dotnet/docfx/pull/9871)
- docs: Fix URL in markdown and match to html example by
[@&#8203;si618](https://togithub.com/si618) in
[https://github.com/dotnet/docfx/pull/9881](https://togithub.com/dotnet/docfx/pull/9881)
- docs: Fix documentation site build warnings by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9895](https://togithub.com/dotnet/docfx/pull/9895)
- docs: Fix missing docfx.json config docs by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9935](https://togithub.com/dotnet/docfx/pull/9935)
- docs: Fix Docfx.App nuget package usage document by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/9994](https://togithub.com/dotnet/docfx/pull/9994)
- docs: Fix plugin related docs and logs by
[@&#8203;filzrev](https://togithub.com/filzrev) in
[https://github.com/dotnet/docfx/pull/10029](https://togithub.com/dotnet/docfx/pull/10029)

#### New Contributors

- [@&#8203;carlos-regis](https://togithub.com/carlos-regis) made their
first contribution in
[https://github.com/dotnet/docfx/pull/9871](https://togithub.com/dotnet/docfx/pull/9871)
- [@&#8203;si618](https://togithub.com/si618) made their first
contribution in
[https://github.com/dotnet/docfx/pull/9881](https://togithub.com/dotnet/docfx/pull/9881)
- [@&#8203;Patrick8639](https://togithub.com/Patrick8639) made their
first contribution in
[https://github.com/dotnet/docfx/pull/9957](https://togithub.com/dotnet/docfx/pull/9957)

**Full Changelog**:
dotnet/docfx@v2.76.0...v2.77.0

</details>

---

### Configuration

📅 **Schedule**: Branch creation - "after 9pm,before 6am" in timezone
Europe/Zurich, Automerge - At any time (no schedule defined).

🚦 **Automerge**: Enabled.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update
again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR has been generated by [Mend
Renovate](https://www.mend.io/free-developer-tools/renovate/). View
repository job log
[here](https://developer.mend.io/github/buehler/dotnet-operator-sdk).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy40MjEuMCIsInVwZGF0ZWRJblZlciI6IjM3LjQyMS4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJkZXBlbmRlbmNpZXMiXX0=-->

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug-fix Makes the pull request to appear in "Bug Fixes" section of the next release note

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants