Skip to content

Commit 863d691

Browse files
ijklamijklam
authored
make remarks and returns visible in quick info (#16417)
* make `remarks` and `returns` visible in quick info * move `remarks` to the end of summarys add an option to control visibility of `remarks` * format code * fix tests * format code
1 parent 81ae2e7 commit 863d691

38 files changed

+476
-152
lines changed

‎vsintegration/src/FSharp.Editor/Completion/CompletionProvider.fs‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,12 @@ open CancellableTasks
2626
module Logger = Microsoft.VisualStudio.FSharp.Editor.Logger
2727

2828
type internal FSharpCompletionProvider
29-
(workspace: Workspace, serviceProvider: SVsServiceProvider, assemblyContentProvider: AssemblyContentProvider) =
29+
(
30+
workspace: Workspace,
31+
serviceProvider: SVsServiceProvider,
32+
assemblyContentProvider: AssemblyContentProvider,
33+
editorOptions: EditorOptions
34+
) =
3035

3136
inherit FSharpCompletionProviderBase()
3237

@@ -380,7 +385,16 @@ type internal FSharpCompletionProvider
380385
let documentation = List()
381386
let collector = RoslynHelpers.CollectTaggedText documentation
382387
// mix main description and xmldoc by using one collector
383-
XmlDocumentation.BuildDataTipText(documentationBuilder, collector, collector, collector, collector, collector, description)
388+
XmlDocumentation.BuildDataTipText(
389+
documentationBuilder,
390+
collector,
391+
collector,
392+
collector,
393+
collector,
394+
collector,
395+
description,
396+
editorOptions.QuickInfo.ShowRemarks
397+
)
384398

385399
Task.FromResult(CompletionDescription.Create(documentation.ToImmutableArray()))
386400
| _ ->

‎vsintegration/src/FSharp.Editor/Completion/CompletionService.fs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ type internal FSharpCompletionService
2424

2525
let builtInProviders =
2626
ImmutableArray.Create<CompletionProvider>(
27-
FSharpCompletionProvider(workspace, serviceProvider, assemblyContentProvider),
27+
FSharpCompletionProvider(workspace, serviceProvider, assemblyContentProvider, settings),
2828
FSharpCommonCompletionProvider.Create(HashDirectiveCompletionProvider.Create(workspace, projectInfoManager))
2929
)
3030

‎vsintegration/src/FSharp.Editor/Completion/SignatureHelp.fs‎

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ type SignatureHelpData =
5858

5959
[<Shared>]
6060
[<Export(typeof<IFSharpSignatureHelpProvider>)>]
61-
type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvider: SVsServiceProvider) =
61+
type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvider: SVsServiceProvider, editorOptions: EditorOptions) =
6262

6363
let documentationBuilder =
6464
XmlDocumentation.CreateDocumentationBuilder(serviceProvider.XMLMemberIndexService)
@@ -79,7 +79,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
7979
documentationBuilder: IDocumentationBuilder,
8080
sourceText: SourceText,
8181
caretPosition: int,
82-
triggerIsTypedChar: char option
82+
triggerIsTypedChar: char option,
83+
editorOptions: EditorOptions
8384
) =
8485
asyncMaybe {
8586
let textLines = sourceText.Lines
@@ -206,7 +207,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
206207
RoslynHelpers.CollectTaggedText mainDescription,
207208
RoslynHelpers.CollectTaggedText documentation,
208209
method.Description,
209-
false
210+
false,
211+
editorOptions.QuickInfo.ShowRemarks
210212
)
211213

212214
let parameters =
@@ -225,7 +227,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
225227
documentationBuilder,
226228
RoslynHelpers.CollectTaggedText doc,
227229
method.XmlDoc,
228-
p.ParameterName
230+
p.ParameterName,
231+
editorOptions.QuickInfo.ShowRemarks
229232
)
230233

231234
p.Display |> Seq.iter (RoslynHelpers.CollectTaggedText parts)
@@ -292,7 +295,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
292295
sourceText: SourceText,
293296
caretPosition: int,
294297
adjustedColumnInSource: int,
295-
filePath: string
298+
filePath: string,
299+
editorOptions: EditorOptions
296300
) =
297301
asyncMaybe {
298302
let textLine = sourceText.Lines.GetLineFromPosition(adjustedColumnInSource)
@@ -430,7 +434,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
430434
typeParameterMap.Add,
431435
usage.Add,
432436
exceptions.Add,
433-
tooltip
437+
tooltip,
438+
editorOptions.QuickInfo.ShowRemarks
434439
)
435440

436441
let fsharpDocs =
@@ -606,7 +611,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
606611
documentationBuilder: IDocumentationBuilder,
607612
caretPosition: int,
608613
triggerTypedChar: char option,
609-
possibleCurrentSignatureHelpSessionKind: CurrentSignatureHelpSessionKind option
614+
possibleCurrentSignatureHelpSessionKind: CurrentSignatureHelpSessionKind option,
615+
editorOptions: EditorOptions
610616
) =
611617
asyncMaybe {
612618

@@ -655,7 +661,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
655661
sourceText,
656662
caretPosition,
657663
adjustedColumnInSource,
658-
document.FilePath
664+
document.FilePath,
665+
editorOptions
659666
)
660667
| _, Some FunctionApplication when
661668
adjustedColumnChar <> ','
@@ -674,7 +681,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
674681
sourceText,
675682
caretPosition,
676683
adjustedColumnInSource,
677-
document.FilePath
684+
document.FilePath,
685+
editorOptions
678686
)
679687
| _ ->
680688
let! paramInfoLocations = parseResults.FindParameterLocations(Position.fromZ caretLinePos.Line caretLineColumn)
@@ -688,7 +696,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
688696
documentationBuilder,
689697
sourceText,
690698
caretPosition,
691-
triggerTypedChar
699+
triggerTypedChar,
700+
editorOptions
692701
)
693702
}
694703

@@ -722,7 +731,8 @@ type internal FSharpSignatureHelpProvider [<ImportingConstructor>] (serviceProvi
722731
documentationBuilder,
723732
position,
724733
triggerTypedChar,
725-
possibleCurrentSignatureHelpSessionKind
734+
possibleCurrentSignatureHelpSessionKind,
735+
editorOptions
726736
)
727737

728738
match signatureHelpDataOpt with

‎vsintegration/src/FSharp.Editor/DocComments/XMLDocumentation.fs‎

Lines changed: 57 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ type internal IDocumentationBuilder =
100100
processedXml: string *
101101
showExceptions: bool *
102102
showParameters: bool *
103+
showRemarks: bool *
103104
paramName: string option ->
104105
unit
105106

@@ -111,6 +112,7 @@ type internal IDocumentationBuilder =
111112
signature: string *
112113
showExceptions: bool *
113114
showParameters: bool *
115+
showRemarks: bool *
114116
paramName: string option ->
115117
unit
116118

@@ -165,6 +167,7 @@ module internal XmlDocumentation =
165167
| "typeref" ->
166168
for attr in el.Attributes() do
167169
WriteAttribute collector attr "name" (tagParameter >> collector.Add)
170+
| "br" -> AppendHardLine collector
168171
| _ -> WriteNodes collector (el.Nodes())
169172
| _ -> ()
170173

@@ -210,13 +213,34 @@ module internal XmlDocumentation =
210213
with _ ->
211214
None
212215

213-
member _.CollectSummary(collector: ITaggedTextCollector) =
216+
member _.CollectSummary(collector: ITaggedTextCollector, showRemarks) =
214217
match Seq.tryHead (doc.Descendants(XName.op_Implicit "summary")) with
215218
| None -> ()
216219
| Some el ->
217220
EnsureHardLine collector
218221
WriteElement collector el
219222

223+
match Seq.tryHead (doc.Descendants(XName.op_Implicit "returns")) with
224+
| None -> ()
225+
| Some el ->
226+
AppendHardLine collector
227+
AppendHardLine collector
228+
AppendOnNewLine collector (SR.ReturnsHeader())
229+
AppendHardLine collector
230+
collector.Add(tagSpace " ")
231+
WriteElement collector el
232+
233+
if showRemarks then
234+
match Seq.tryHead (doc.Descendants(XName.op_Implicit "remarks")) with
235+
| None -> ()
236+
| Some el ->
237+
AppendHardLine collector
238+
AppendHardLine collector
239+
AppendOnNewLine collector (SR.RemarksHeader())
240+
AppendHardLine collector
241+
collector.Add(tagSpace " ")
242+
WriteElement collector el
243+
220244
member this.CollectParameter(collector: ITaggedTextCollector, paramName: string) =
221245
match tryFindParameter paramName with
222246
| None -> ()
@@ -294,11 +318,12 @@ module internal XmlDocumentation =
294318
exnCollector: ITaggedTextCollector,
295319
xmlDocReader: XmlDocReader,
296320
showExceptions,
297-
showParameters
321+
showParameters,
322+
showRemarks
298323
) =
299324
AppendHardLine xmlCollector
300325
xmlCollector.StartXMLDoc()
301-
xmlDocReader.CollectSummary(xmlCollector)
326+
xmlDocReader.CollectSummary(xmlCollector, showRemarks)
302327

303328
if (showParameters) then
304329
xmlDocReader.CollectParameters xmlCollector
@@ -315,13 +340,14 @@ module internal XmlDocumentation =
315340
processedXml,
316341
showExceptions,
317342
showParameters,
343+
showRemarks,
318344
paramName
319345
) =
320346
match XmlDocReader.TryCreate processedXml with
321347
| Some xmlDocReader ->
322348
match paramName with
323349
| Some paramName -> xmlDocReader.CollectParameter(xmlCollector, paramName)
324-
| None -> AppendMemberData(xmlCollector, exnCollector, xmlDocReader, showExceptions, showParameters)
350+
| None -> AppendMemberData(xmlCollector, exnCollector, xmlDocReader, showExceptions, showParameters, showRemarks)
325351
| None -> ()
326352

327353
/// Append Xml documentation contents into the StringBuilder
@@ -333,14 +359,15 @@ module internal XmlDocumentation =
333359
signature: string,
334360
showExceptions: bool,
335361
showParameters: bool,
362+
showRemarks,
336363
paramName: string option
337364
) =
338365
try
339366
match GetMemberIndexOfAssembly(fileName) with
340367
| Some(index) ->
341-
let _, idx = index.ParseMemberSignature(signature)
368+
let ok, idx = index.ParseMemberSignature(signature)
342369

343-
if idx <> 0u then
370+
if Com.Succeeded(ok) then
344371
let ok, xml = index.GetMemberXML(idx)
345372

346373
if Com.Succeeded(ok) then
@@ -351,6 +378,7 @@ module internal XmlDocumentation =
351378
xml,
352379
showExceptions,
353380
showParameters,
381+
showRemarks,
354382
paramName
355383
)
356384
| None -> ()
@@ -367,6 +395,7 @@ module internal XmlDocumentation =
367395
xml,
368396
showExceptions,
369397
showParameters,
398+
showRemarks,
370399
paramName
371400
) =
372401
match xml with
@@ -379,6 +408,7 @@ module internal XmlDocumentation =
379408
signature,
380409
showExceptions,
381410
showParameters,
411+
showRemarks,
382412
paramName
383413
)
384414
| FSharpXmlDoc.FromXmlText(xmlDoc) ->
@@ -391,6 +421,7 @@ module internal XmlDocumentation =
391421
processedXml,
392422
showExceptions,
393423
showParameters,
424+
showRemarks,
394425
paramName
395426
)
396427

@@ -417,7 +448,13 @@ module internal XmlDocumentation =
417448
OverLoadsLimit = 5
418449
}
419450

420-
let BuildSingleTipText (documentationProvider: IDocumentationBuilder, dataTipElement: ToolTipElement, limits: LineLimits) =
451+
let BuildSingleTipText
452+
(
453+
documentationProvider: IDocumentationBuilder,
454+
dataTipElement: ToolTipElement,
455+
limits: LineLimits,
456+
showRemarks: bool
457+
) =
421458

422459
let {
423460
LineLimit = lineLimit
@@ -481,7 +518,7 @@ module internal XmlDocumentation =
481518
AppendHardLine usageCollector
482519
r |> Seq.iter usageCollector.Add)
483520

484-
AppendXmlComment(documentationProvider, xmlCollector, exnCollector, item0.XmlDoc, true, false, item0.ParamName)
521+
AppendXmlComment(documentationProvider, xmlCollector, exnCollector, item0.XmlDoc, true, false, showRemarks, item0.ParamName)
485522

486523
ProcessGenericParameters item0.TypeMapping
487524

@@ -505,7 +542,8 @@ module internal XmlDocumentation =
505542
exnCollector,
506543
showText,
507544
showExceptions,
508-
showParameters
545+
showParameters,
546+
showRemarks
509547
) =
510548
let textCollector: ITaggedTextCollector =
511549
TextSanitizingCollector(textCollector, lineLimit = 45) :> _
@@ -590,6 +628,7 @@ module internal XmlDocumentation =
590628
item0.XmlDoc,
591629
showExceptions,
592630
showParameters,
631+
showRemarks,
593632
item0.ParamName
594633
)
595634

@@ -614,7 +653,8 @@ module internal XmlDocumentation =
614653
typeParameterMapCollector,
615654
usageCollector,
616655
exnCollector,
617-
ToolTipText(dataTipText)
656+
ToolTipText(dataTipText),
657+
showRemarks
618658
) =
619659
BuildTipText(
620660
documentationProvider,
@@ -626,10 +666,11 @@ module internal XmlDocumentation =
626666
exnCollector,
627667
true,
628668
true,
629-
false
669+
false,
670+
showRemarks
630671
)
631672

632-
let BuildMethodOverloadTipText (documentationProvider, textCollector, xmlCollector, ToolTipText(dataTipText), showParams) =
673+
let BuildMethodOverloadTipText (documentationProvider, textCollector, xmlCollector, ToolTipText(dataTipText), showParams, showRemarks) =
633674
BuildTipText(
634675
documentationProvider,
635676
dataTipText,
@@ -640,17 +681,19 @@ module internal XmlDocumentation =
640681
ignore,
641682
false,
642683
false,
643-
showParams
684+
showParams,
685+
showRemarks
644686
)
645687

646-
let BuildMethodParamText (documentationProvider, xmlCollector, xml, paramName) =
688+
let BuildMethodParamText (documentationProvider, xmlCollector, xml, paramName, showRemarks) =
647689
AppendXmlComment(
648690
documentationProvider,
649691
TextSanitizingCollector(xmlCollector),
650692
TextSanitizingCollector(xmlCollector),
651693
xml,
652694
false,
653695
true,
696+
showRemarks,
654697
Some paramName
655698
)
656699

0 commit comments

Comments
 (0)