Resolve `<see cref>` in XML doc comments like C#

オープン
  • 何か問題がありますか？
#20,640 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 2 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
fsharp
領域
compilers, devtools, documentation

調査の方向性

Start by reading the XML documentation flow at XmlDocFileWriter.WriteXmlDocFile and the XML doc ranges from #20637, then inspect XmlDocSigOfVal and the related rename work in #20638. Done means the stated first-cut cref forms resolve against the final environment, emit documentation IDs or !:Text, report FS3390 when unresolved, and support the described editor behavior.

索引モデルが issue の本文から書いたものです。

説明

Feature Request Needs-Triage

Is your feature request related to a problem? Please describe.

<see cref="…"/>, <seealso cref>, <exception cref> and <permission cref> in F# /// comments are plain text to the compiler and the IDE:

  • --doc copies the attribute verbatim (XmlDocFileWriter.WriteXmlDocFile), so <see cref="Parse"/> reaches the .xml file as Parse. C# writes the documentation ID (M:Ns.Parser.Parse(System.String)), and tools that read the file (DocFX, fsdocs, Visual Studio tooltips of the consuming project) resolve IDs, not source names. The unresolved-cref diagnostic already exists (xmlDocUnresolvedCrossReference, FS3390 group) but is never raised.
  • In the editor, a cref is not a symbol: Go To Definition does nothing on it, renaming the type or member leaves it stale, and the tooltip prints the raw text.

Describe the solution you'd like

The same as C#, built on the XML doc ranges from #20637:

  1. The checker resolves each cref against the file's final environment (so it can point forward, as in C#): the enclosing type's members first, then values, types and modules — the nameof resolution order. A resolved cref is reported as a related symbol use of a new kind (RelatedSymbolUseKind.XmlDocCref), opt-in like XmlDocParameter in #20637, so symbol search is not bloated.
  2. --doc writes the documentation ID of the resolved symbol; an unresolved cref is written as !:Text and reported under FS3390. A cref that already carries a prefix (T:, M:, …) is kept as is.
  3. The editor: Rename rewrites the last segment of the cref (#20638 already passes all related kinds to Rename), Go To Definition works on it, and the tooltip shows the resolved name.

A first cut would cover types, modules, union cases, fields, properties, events and non-overloaded methods, and leave M(int) overload syntax, List{T} generics and operators for later.

Describe alternatives you've considered

  • Resolving where each doc comment is converted: a type's doc is converted before the rest of its recursive group and its members exist, so forward references would not resolve.
  • Producing the IDs during checking: XmlDocSigOfVal needs the generalized type and ValReprInfo, and the IDs are cached on the Val; they have to be made when --doc writes the file.

Additional context

Questions before any code:

  1. Should Find All References list crefs? C# does; #20637/#20638 keep <param> names out of it.
  2. Is rewriting the .xml output a compiler change that can go in behind --doc, or does it need a language suggestion first?
  3. Should FS3390 for an unresolved cref stay opt-in, like the rest of that warning?

Related: #20630, #20637, #20638, #15134, #20591.

主要言語
F#
スター
4.3k
フォーク
884
平均マージ
2日 11時間
マージ済み PR（30日）
73

環境構築

Codespaces で開く

このプロジェクトの開発コンテナを、あなたの GitHub アカウントでブラウザ上に起動します。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

dotnet/fsharp のほかの issue

dotnet/fsharp の issue をすべて見る

似ている issue

Compilers の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。