Merge pull request #790 from davedawkins/issue-789

Documentation and tests for <seealso> when cref omits arguments

Author: nojaf

RELEASE_NOTES.md

@@ -1,3 +1,7 @@
+## 17.2.2
+
+* Improvement for `<seealso/>` [#789](https://github.com/fsprojects/FSharp.Formatting/issues/789)
+
 ## 17.2.1
 
 * Fix support for `<exclude/>` [#786](https://github.com/fsprojects/FSharp.Formatting/issues/786)

docs/apidocs.fsx

@@ -169,6 +169,44 @@ type GenericClass2<'T>() =
 /// and <see cref="M:TheNamespace.GenericClass2`1.GenericMethod``1(`0,``0)" />
 let referringFunction2 () = "result"
 
+(**
+### Cross-referencing with &lt;seealso&gt;
+
+Use `<seealso cref="..."/>` within `<summary>` to create cross-references.
+
+For example:
+*)
+
+module Forest =
+
+    /// <summary>
+    /// Find at most <c>limit</c> foxes in current forest
+    ///
+    /// See also: <seealso cref="M:App.Forest.findSquirrels(System.Int32)"/>
+    /// </summary>
+    let findFoxes (limit : int) = []
+
+    /// <summary>
+    /// Find at most <c>limit</c> squirrels in current forest
+    ///
+    /// See also: <seealso cref="M:App.Forest.findFoxes(System.Int32)"/>
+    /// </summary>
+    let findSquirrels (limit : int) = []
+
+
+(** You can find the correct value for `cref` in the generated `.xml` documentation file (this will be generated alongside the assembly's `.dll``).
+
+You can also omit the `cref`'s arguments, and `fsdocs` will make an attempt to find the first member that matches.
+
+For example:
+```
+    /// See also: <seealso cref="M:App.Forest.findSquirrels"/>
+```
+
+If the member cannot be found, a link to the containing module/type will be used instead.
+*)
+
+
 (**
 ### Classic XMl Doc Comments: Excluding APIs from the docs
 

src/FSharp.Formatting.ApiDocs/GenerateModel.fs

@@ -858,6 +858,15 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
         else
             None
 
+    let tryGetShortMemberNameFromMemberName (memberName: string) =
+        let sub = removeParen memberName
+        let lastPeriod = sub.LastIndexOf(".")
+
+        if lastPeriod > 0 then
+            Some(memberName.Substring(lastPeriod + 1))
+        else
+            None
+
     let getMemberName keepParts hasModuleSuffix (memberNameNoParen: string) =
         let splits = memberNameNoParen.Split('.') |> Array.toList
 
@@ -992,6 +1001,13 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
                 let simple = getMemberName 1 false typeName
                 externalDocsLink false simple typeName typeName
 
+    let mfvToCref (mfv: FSharpMemberOrFunctionOrValue) =
+        let entityUrlBaseName = getUrlBaseNameForRegisteredEntity mfv.DeclaringEntity.Value
+
+        { IsInternal = true
+          ReferenceLink = internalCrossReferenceForMember entityUrlBaseName mfv
+          NiceName = mfv.DeclaringEntity.Value.DisplayName + "." + mfv.DisplayName }
+
     let tryResolveCrossReferenceForMemberByXmlSig (memberXmlSig: string) =
         assert
             (memberXmlSig.StartsWith("M:")
@@ -1000,13 +1016,7 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
              || memberXmlSig.StartsWith("E:"))
 
         match xmlDocNameToSymbol.TryGetValue(memberXmlSig) with
-        | true, (:? FSharpMemberOrFunctionOrValue as memb) when memb.DeclaringEntity.IsSome ->
-            let entityUrlBaseName = getUrlBaseNameForRegisteredEntity memb.DeclaringEntity.Value
-
-            { IsInternal = true
-              ReferenceLink = internalCrossReferenceForMember entityUrlBaseName memb
-              NiceName = memb.DeclaringEntity.Value.DisplayName + "." + memb.DisplayName }
-            |> Some
+        | true, (:? FSharpMemberOrFunctionOrValue as memb) when memb.DeclaringEntity.IsSome -> memb |> mfvToCref |> Some
         | _ ->
             // If we can't find the exact symbol for the member, don't despair, look for the type
             let memberName = memberXmlSig.Substring(2) |> removeParen
@@ -1019,10 +1029,19 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
                 | true, (:? FSharpEntity as entity) ->
                     let urlBaseName = getUrlBaseNameForRegisteredEntity entity
 
-                    Some
-                        { IsInternal = true
-                          ReferenceLink = internalCrossReference urlBaseName
-                          NiceName = getMemberName 2 entity.HasFSharpModuleSuffix memberName }
+                    // See if we find the member that was intended, otherwise default to containing entity
+                    tryGetShortMemberNameFromMemberName memberName
+                    |> Option.bind (fun shortName ->
+                        entity.MembersFunctionsAndValues
+                        |> Seq.tryFind (fun mfv -> mfv.DisplayName = shortName))
+                    |> function
+                        | Some mb -> Some(mfvToCref mb)
+                        | None ->
+                            Some
+                                { IsInternal = true
+                                  ReferenceLink = internalCrossReference urlBaseName
+                                  NiceName = getMemberName 2 entity.HasFSharpModuleSuffix memberName }
+
                 | _ ->
                     // A reference to something external, currently assumed to be in .NET
                     let simple = getMemberName 2 false memberName

tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs

@@ -127,6 +127,22 @@ let generateApiDocs (libraries: string list) (format: OutputFormat) useMdComment
 
 do FSharp.Formatting.TestHelpers.enableLogging ()
 
+[<Test>]
+[<TestCaseSource("formats")>]
+let ``ApiDocs seealso can find members`` (format: OutputFormat) =
+    let library = testBin </> "TestLib3.dll" |> fullpath
+
+    let files = generateApiDocs [ library ] format false "TestLib3"
+
+    let (textA, textB) =
+        if format = OutputFormat.Html then
+            "seealso.html#disposeOnUnmount", "seealso.html#unsubscribeOnUnmount"
+        else
+            "seealso#disposeOnUnmount", "seealso#unsubscribeOnUnmount"
+
+    files.[(sprintf "test-seealso.%s" format.Extension)] |> shouldContainText textA
+
+    files.[(sprintf "test-seealso.%s" format.Extension)] |> shouldContainText textB
 
 [<Test>]
 [<TestCaseSource("formats")>]

tests/FSharp.ApiDocs.Tests/files/TestLib3/SeeAlso.fs

@@ -0,0 +1,18 @@
+/// <summary>
+/// DOM low-level helper functions
+/// </summary>
+module Test.SeeAlso
+
+/// <summary>
+/// Dispose all given items when the parent <c>SutilElement</c> is unmounted. Each item should implement <c>System.IDisposable</c>.
+///
+/// See also: <seealso cref="M:Test.SeeAlso.unsubscribeOnUnmount"/>
+/// </summary>
+let disposeOnUnmount (ds: System.IDisposable list) = ignore ds
+
+/// <summary>
+/// Call each function of type `(unit -> unit)` when the element is unmounted
+///
+/// See also: <seealso cref="M:Test.SeeAlso.disposeOnUnmount"/>
+/// </summary>
+let unsubscribeOnUnmount (ds: (unit -> unit) list) = ignore ds

tests/FSharp.ApiDocs.Tests/files/TestLib3/TestLib3.fsproj

@@ -5,6 +5,7 @@
     <OutputPath>..\bin\$(Configuration)</OutputPath>
   </PropertyGroup>
   <ItemGroup>
+    <Compile Include="SeeAlso.fs" />
     <Compile Include="DOM.fs" />
     <Compile Include="Library3.fs" />
     <Compile Include="UndocumentedModule.fs" />