From 0e99f35662bf092bb1593a54f583d1bae23ca0b8 Mon Sep 17 00:00:00 2001 From: Ademar Gonzalez Date: Tue, 21 Jul 2015 11:08:23 -0400 Subject: [PATCH 1/8] support for all recommended xml tags https://msdn.microsoft.com/en-us/library/vstudio/5ast78ax(v=vs.100).aspx --- src/FSharp.MetadataFormat/Main.fs | 149 +++++++++++++++++++----------- 1 file changed, 97 insertions(+), 52 deletions(-) mode change 100644 => 100755 src/FSharp.MetadataFormat/Main.fs diff --git a/src/FSharp.MetadataFormat/Main.fs b/src/FSharp.MetadataFormat/Main.fs old mode 100644 new mode 100755 index 6631b06da..b82877a5b --- a/src/FSharp.MetadataFormat/Main.fs +++ b/src/FSharp.MetadataFormat/Main.fs @@ -523,77 +523,122 @@ module Reader = KeyValuePair(k, html) ] Comment.Create(blurb, full, sections) - let readXmlComment (urlMap : IUrlHolder) (doc : XElement) = - + let readXmlComment (urlMap : IUrlHolder) (doc : XElement) = + let full = new StringBuilder() - let readElement (e : XElement) = - Seq.iter (fun (x : XNode) -> - if x.NodeType = XmlNodeType.Text then + let rec readElement (e : XElement) = + Seq.iter (fun (x : XNode) -> + if x.NodeType = XmlNodeType.Text then full.Append((x :?> XText).Value) |> ignore elif x.NodeType = XmlNodeType.Element then let elem = x :?> XElement - if elem.Name.LocalName = "see" || elem.Name.LocalName = "seealso" then - let cref = elem.Attribute(XName.Get "cref") - if cref <> null then - if System.String.IsNullOrEmpty(cref.Value) || cref.Value.Length < 3 then - failwithf "Invalid cref specified in: %A" doc - match urlMap.ResolveCref cref.Value with - | Some (reference) -> + match elem.Name.LocalName with + | "list" -> + full.Append("") |> ignore + | "item" -> + full.Append("
  • ") |> ignore + full.Append(elem.Value) |> ignore + full.Append("
    • ") |> ignore + | "para" -> + full.Append("

    ") |> ignore + full.Append(elem.Value) |> ignore + full.Append("

    ") |> ignore + | "see" + | "seealso" -> + let cref = elem.Attribute(XName.Get "cref") + if cref <> null then + if System.String.IsNullOrEmpty(cref.Value) || cref.Value.Length < 3 then + failwithf "Invalid cref specified in: %A" doc + match urlMap.ResolveCref cref.Value with + | Some (reference) -> full.AppendFormat("{1}", reference.ReferenceLink, reference.NiceName) |> ignore - | _ -> + | _ -> full.AppendFormat("UNRESOLVED({0})", cref.Value) |> ignore + | _ -> + () ) (e.Nodes()) readElement doc full.Append("
    ") |> ignore - let paras = doc.Descendants(XName.Get("para")) - Seq.iter (fun (x : XElement) -> - full.Append("

    ") |> ignore - readElement x - full.Append("

    ") |> ignore ) paras - - let paras = doc.Descendants(XName.Get("remarks")) - Seq.iter (fun (x : XElement) -> - full.Append("

    ") |> ignore - readElement x - full.Append("

    ") |> ignore ) paras - + for e in doc.Descendants(XName.Get "summary") do + full.Append("

    ") |> ignore + readElement e + full.Append("

    ") |> ignore + + let parameters = doc.Descendants(XName.Get "params") + + if Seq.length parameters > 0 then + full.Append("

    Parameters

    ") |> ignore + full.Append("
    ") |> ignore + for e in parameters do + let name = e.Attribute(XName.Get "name").Value + let description = e.Value + full.AppendFormat("
    {0}

    {1}

    ", name, description) |> ignore + full.Append("
    ") |> ignore + + for e in doc.Descendants(XName.Get "returns") do + full.Append("

    ") |> ignore + let description = e.Value + full.AppendFormat("Returns: {0}",description) |> ignore + full.Append("

    ") |> ignore + + let exceptions = doc.Descendants(XName.Get "exceptions") + if Seq.length exceptions > 0 then + full.Append("

    Exceptions

    ") |> ignore + full.Append("") |> ignore + for e in exceptions do + let cref = e.Attribute(XName.Get "cref") + if cref <> null then + if System.String.IsNullOrEmpty(cref.Value) || cref.Value.Length < 3 then + failwithf "Invalid cref specified in: %A" doc + match urlMap.ResolveCref cref.Value with + | Some (reference) -> + full.AppendFormat("", reference.ReferenceLink, reference.NiceName,e.Value) |> ignore + | _ -> + full.AppendFormat("", cref.Value) |> ignore + full.Append("
    {1}{2}
    UNRESOLVED({0})
    ") |> ignore + + let remarks = doc.Descendants(XName.Get "remarks") + if Seq.length remarks > 0 then + full.Append("

    Remarks

    ") |> ignore + for e in remarks do + full.Append("

    ") |> ignore + readElement e + full.Append("

    ") |> ignore + // TODO: process param, returns tags, note that given that FSharp.Formatting infers the signature // via reflection this tags are not so important in F# let str = full.ToString() Comment.Create(str, str, [KeyValuePair("", str)]) - let readCommentAndCommands (ctx:ReadingContext) xmlSig = - match ctx.XmlMemberLookup(xmlSig) with - | None -> + let readCommentAndCommands (ctx:ReadingContext) xmlSig = + match ctx.XmlMemberLookup(xmlSig) with + | None -> if not (System.String.IsNullOrEmpty xmlSig) then Log.logf "Warning: Could not find documentation for '%s'! (You can ignore this message when you have not written documentation for this member)" xmlSig dict[], Comment.Empty | Some el -> - let sum = el.Element(XName.Get "summary") - if sum = null then - if String.IsNullOrEmpty el.Value then - dict[], Comment.Empty - else - dict[], (Comment.Create ("", el.Value, [])) - else - if ctx.MarkdownComments then - let lines = removeSpaces sum.Value - let cmds = new System.Collections.Generic.Dictionary<_, _>() - let text = - lines |> Seq.filter (function - | String.StartsWithWrapped ("[", "]") (ParseCommand(k, v), rest) -> - cmds.Add(k, v) - false - | _ -> true) |> String.concat "\n" - let doc = - Literate.ParseMarkdownString - ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), - formatAgent=ctx.FormatAgent, compilerOptions=ctx.CompilerOptions ) - cmds :> IDictionary<_, _>, readMarkdownComment doc - else - let cmds = new System.Collections.Generic.Dictionary<_, _>() - cmds :> IDictionary<_, _>, readXmlComment ctx.UrlMap sum + if ctx.MarkdownComments then + let sum = el.Element(XName.Get "summary") + let value = if sum = null then el.Value else sum.Value + let lines = removeSpaces value + let cmds = new System.Collections.Generic.Dictionary<_, _>() + let text = + lines |> Seq.filter (function + | String.StartsWithWrapped ("[", "]") (ParseCommand(k, v), rest) -> + cmds.Add(k, v) + false + | _ -> true) |> String.concat "\n" + let doc = + Literate.ParseMarkdownString + ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), + formatAgent=ctx.FormatAgent, compilerOptions=ctx.CompilerOptions ) + cmds :> IDictionary<_, _>, readMarkdownComment doc + else + let cmds = new System.Collections.Generic.Dictionary<_, _>() + cmds :> IDictionary<_, _>, readXmlComment ctx.UrlMap el let readComment ctx xmlSig = readCommentAndCommands ctx xmlSig |> snd From 71b8e972147679e9fe2ce020d4c8d714c8f55a07 Mon Sep 17 00:00:00 2001 From: Ademar Gonzalez Date: Tue, 21 Jul 2015 11:08:23 -0400 Subject: [PATCH 2/8] support for all recommended xml tags https://msdn.microsoft.com/en-us/library/vstudio/5ast78ax(v=vs.100).aspx --- src/FSharp.MetadataFormat/Main.fs | 136 +++++++++++++++++++----------- 1 file changed, 89 insertions(+), 47 deletions(-) mode change 100644 => 100755 src/FSharp.MetadataFormat/Main.fs diff --git a/src/FSharp.MetadataFormat/Main.fs b/src/FSharp.MetadataFormat/Main.fs old mode 100644 new mode 100755 index 38a27c189..94419921b --- a/src/FSharp.MetadataFormat/Main.fs +++ b/src/FSharp.MetadataFormat/Main.fs @@ -526,41 +526,91 @@ module Reader = KeyValuePair(k, html) ] Comment.Create(blurb, full, sections) - let readXmlComment (urlMap : IUrlHolder) (doc : XElement) = - + let readXmlComment (urlMap : IUrlHolder) (doc : XElement) = + let full = new StringBuilder() - let readElement (e : XElement) = - Seq.iter (fun (x : XNode) -> - if x.NodeType = XmlNodeType.Text then + let rec readElement (e : XElement) = + Seq.iter (fun (x : XNode) -> + if x.NodeType = XmlNodeType.Text then full.Append((x :?> XText).Value) |> ignore elif x.NodeType = XmlNodeType.Element then let elem = x :?> XElement - if elem.Name.LocalName = "see" || elem.Name.LocalName = "seealso" then - let cref = elem.Attribute(XName.Get "cref") - if cref <> null then - if System.String.IsNullOrEmpty(cref.Value) || cref.Value.Length < 3 then - failwithf "Invalid cref specified in: %A" doc - match urlMap.ResolveCref cref.Value with - | Some (reference) -> + match elem.Name.LocalName with + | "list" -> + full.Append("
      ") |> ignore + readElement elem + full.Append("
    ") |> ignore + | "item" -> + full.Append("
  • ") |> ignore + full.Append(elem.Value) |> ignore + full.Append("
    • ") |> ignore + | "para" -> + full.Append("

    ") |> ignore + full.Append(elem.Value) |> ignore + full.Append("

    ") |> ignore + | "see" + | "seealso" -> + let cref = elem.Attribute(XName.Get "cref") + if cref <> null then + if System.String.IsNullOrEmpty(cref.Value) || cref.Value.Length < 3 then + failwithf "Invalid cref specified in: %A" doc + match urlMap.ResolveCref cref.Value with + | Some (reference) -> full.AppendFormat("{1}", reference.ReferenceLink, reference.NiceName) |> ignore - | _ -> + | _ -> full.AppendFormat("UNRESOLVED({0})", cref.Value) |> ignore + | _ -> + () ) (e.Nodes()) readElement doc full.Append("
    ") |> ignore - let paras = doc.Descendants(XName.Get("para")) - Seq.iter (fun (x : XElement) -> - full.Append("

    ") |> ignore - readElement x - full.Append("

    ") |> ignore ) paras - - let paras = doc.Descendants(XName.Get("remarks")) - Seq.iter (fun (x : XElement) -> - full.Append("

    ") |> ignore - readElement x - full.Append("

    ") |> ignore ) paras - + for e in doc.Descendants(XName.Get "summary") do + full.Append("

    ") |> ignore + readElement e + full.Append("

    ") |> ignore + + let parameters = doc.Descendants(XName.Get "params") + + if Seq.length parameters > 0 then + full.Append("

    Parameters

    ") |> ignore + full.Append("
    ") |> ignore + for e in parameters do + let name = e.Attribute(XName.Get "name").Value + let description = e.Value + full.AppendFormat("
    {0}

    {1}

    ", name, description) |> ignore + full.Append("
    ") |> ignore + + for e in doc.Descendants(XName.Get "returns") do + full.Append("

    ") |> ignore + let description = e.Value + full.AppendFormat("Returns: {0}",description) |> ignore + full.Append("

    ") |> ignore + + let exceptions = doc.Descendants(XName.Get "exceptions") + if Seq.length exceptions > 0 then + full.Append("

    Exceptions

    ") |> ignore + full.Append("") |> ignore + for e in exceptions do + let cref = e.Attribute(XName.Get "cref") + if cref <> null then + if System.String.IsNullOrEmpty(cref.Value) || cref.Value.Length < 3 then + failwithf "Invalid cref specified in: %A" doc + match urlMap.ResolveCref cref.Value with + | Some (reference) -> + full.AppendFormat("", reference.ReferenceLink, reference.NiceName,e.Value) |> ignore + | _ -> + full.AppendFormat("", cref.Value) |> ignore + full.Append("
    {1}{2}
    UNRESOLVED({0})
    ") |> ignore + + let remarks = doc.Descendants(XName.Get "remarks") + if Seq.length remarks > 0 then + full.Append("

    Remarks

    ") |> ignore + for e in remarks do + full.Append("

    ") |> ignore + readElement e + full.Append("

    ") |> ignore + // TODO: process param, returns tags, note that given that FSharp.Formatting infers the signature // via reflection this tags are not so important in F# let str = full.ToString() @@ -640,37 +690,29 @@ module Reader = Log.verbf "Could not find documentation for '%s'! (You can ignore this message when you have not written documentation for this member)" xmlSig dict[], Comment.Empty | Some el -> - let sum = el.Element(XName.Get "summary") - if sum = null then - if String.IsNullOrEmpty el.Value then - dict[], Comment.Empty - else - dict[], (Comment.Create ("", el.Value, [])) - else - let lines = removeSpaces sum.Value + if ctx.MarkdownComments then + let sum = el.Element(XName.Get "summary") + let value = if sum = null then el.Value else sum.Value + let lines = removeSpaces value let cmds = new System.Collections.Generic.Dictionary<_, _>() let findCommand = (function | String.StartsWithWrapped ("[", "]") (ParseCommand(k, v), rest) -> Some (k, v) | _ -> None) - if ctx.MarkdownComments then - let text = - lines |> Seq.filter (findCommand >> (function + let text = + lines |> Seq.filter (findCommand >> (function | Some (k, v) -> cmds.Add(k, v) false | _ -> true)) |> String.concat "\n" - let doc = - Literate.ParseMarkdownString - ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), - formatAgent=ctx.FormatAgent, compilerOptions=ctx.CompilerOptions ) - |> (addMissingLinkToTypes ctx) - cmds :> IDictionary<_, _>, readMarkdownComment doc - else - lines - |> Seq.choose findCommand - |> Seq.iter (fun (k, v) -> cmds.Add(k,v)) - cmds :> IDictionary<_, _>, readXmlComment ctx.UrlMap sum + let doc = + Literate.ParseMarkdownString + ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), + formatAgent=ctx.FormatAgent, compilerOptions=ctx.CompilerOptions ) + cmds :> IDictionary<_, _>, readMarkdownComment doc + else + let cmds = new System.Collections.Generic.Dictionary<_, _>() + cmds :> IDictionary<_, _>, readXmlComment ctx.UrlMap el let readComment ctx xmlSig = readCommentAndCommands ctx xmlSig |> snd From eef2f184133716721949fee00da1b499f5f3d246 Mon Sep 17 00:00:00 2001 From: Ademar Gonzalez Date: Thu, 26 Nov 2015 10:23:55 -0500 Subject: [PATCH 3/8] fix another conflict --- src/FSharp.MetadataFormat/Main.fs | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/src/FSharp.MetadataFormat/Main.fs b/src/FSharp.MetadataFormat/Main.fs index 801c436cc..3c79f9769 100755 --- a/src/FSharp.MetadataFormat/Main.fs +++ b/src/FSharp.MetadataFormat/Main.fs @@ -616,7 +616,6 @@ module Reader = let str = full.ToString() Comment.Create(str, str, [KeyValuePair("", str)]) -<<<<<<< HEAD /// Returns all indirect links in a specified span node let rec collectSpanIndirectLinks span = seq { match span with @@ -684,14 +683,9 @@ module Reader = LiterateDocument(replacedParagraphs, doc.FormattedTips, doc.DefinedLinks, doc.Source, doc.SourceFile, doc.Errors) - let readCommentAndCommands (ctx:ReadingContext) xmlSig = - match ctx.XmlMemberLookup(xmlSig) with - | None -> -======= let readCommentAndCommands (ctx:ReadingContext) xmlSig = match ctx.XmlMemberLookup(xmlSig) with | None -> ->>>>>>> origin/master if not (System.String.IsNullOrEmpty xmlSig) then Log.verbf "Could not find documentation for '%s'! (You can ignore this message when you have not written documentation for this member)" xmlSig dict[], Comment.Empty @@ -701,7 +695,6 @@ module Reader = let value = if sum = null then el.Value else sum.Value let lines = removeSpaces value let cmds = new System.Collections.Generic.Dictionary<_, _>() -<<<<<<< HEAD let findCommand = (function | String.StartsWithWrapped ("[", "]") (ParseCommand(k, v), rest) -> Some (k, v) @@ -712,14 +705,6 @@ module Reader = cmds.Add(k, v) false | _ -> true)) |> String.concat "\n" -======= - let text = - lines |> Seq.filter (function - | String.StartsWithWrapped ("[", "]") (ParseCommand(k, v), rest) -> - cmds.Add(k, v) - false - | _ -> true) |> String.concat "\n" ->>>>>>> origin/master let doc = Literate.ParseMarkdownString ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), From 4f4c3c288f01abc97eedb4976bd5a8cf6e5b8b37 Mon Sep 17 00:00:00 2001 From: Ademar Gonzalez Date: Thu, 26 Nov 2015 11:13:15 -0500 Subject: [PATCH 4/8] disable invalid test When MarkdownComments is false we want to render all comments. --- tests/FSharp.MetadataFormat.Tests/Tests.fs | 1 + 1 file changed, 1 insertion(+) mode change 100644 => 100755 tests/FSharp.MetadataFormat.Tests/Tests.fs diff --git a/tests/FSharp.MetadataFormat.Tests/Tests.fs b/tests/FSharp.MetadataFormat.Tests/Tests.fs old mode 100644 new mode 100755 index 0213a895f..8abdf5b5f --- a/tests/FSharp.MetadataFormat.Tests/Tests.fs +++ b/tests/FSharp.MetadataFormat.Tests/Tests.fs @@ -428,6 +428,7 @@ open System.Diagnostics open FSharp.Formatting.Common [] +[] let ``MetadataFormat omit works without markdown``() = let binDir = root @@ "files/FsLib/bin/Debug" let library = binDir @@ "FsLib2.dll" From 686cb9ac3b4331b78eaa2a4b400700ea03afc862 Mon Sep 17 00:00:00 2001 From: Ademar Gonzalez Date: Thu, 26 Nov 2015 11:34:34 -0500 Subject: [PATCH 5/8] fix: return addMissingLinkToTypes --- src/FSharp.MetadataFormat/Main.fs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/FSharp.MetadataFormat/Main.fs b/src/FSharp.MetadataFormat/Main.fs index 3c79f9769..dd9b5fa54 100755 --- a/src/FSharp.MetadataFormat/Main.fs +++ b/src/FSharp.MetadataFormat/Main.fs @@ -705,10 +705,11 @@ module Reader = cmds.Add(k, v) false | _ -> true)) |> String.concat "\n" - let doc = - Literate.ParseMarkdownString - ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), - formatAgent=ctx.FormatAgent, compilerOptions=ctx.CompilerOptions ) + let doc = + Literate.ParseMarkdownString + ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), + formatAgent=ctx.FormatAgent, compilerOptions=ctx.CompilerOptions ) + |> (addMissingLinkToTypes ctx) cmds :> IDictionary<_, _>, readMarkdownComment doc else let cmds = new System.Collections.Generic.Dictionary<_, _>() From 59971038cba7e87225d13624610aa93e3eff9732 Mon Sep 17 00:00:00 2001 From: Ademar Gonzalez Date: Tue, 1 Dec 2015 13:29:06 -0500 Subject: [PATCH 6/8] the test is indeed correct --- tests/FSharp.MetadataFormat.Tests/Tests.fs | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/FSharp.MetadataFormat.Tests/Tests.fs b/tests/FSharp.MetadataFormat.Tests/Tests.fs index 8abdf5b5f..0213a895f 100755 --- a/tests/FSharp.MetadataFormat.Tests/Tests.fs +++ b/tests/FSharp.MetadataFormat.Tests/Tests.fs @@ -428,7 +428,6 @@ open System.Diagnostics open FSharp.Formatting.Common [] -[] let ``MetadataFormat omit works without markdown``() = let binDir = root @@ "files/FsLib/bin/Debug" let library = binDir @@ "FsLib2.dll" From ef629544e122cc0050f0d9ecc338da0c2b461b3e Mon Sep 17 00:00:00 2001 From: Ademar Gonzalez Date: Tue, 1 Dec 2015 14:10:10 -0500 Subject: [PATCH 7/8] support commands on xml comments --- src/FSharp.MetadataFormat/Main.fs | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/src/FSharp.MetadataFormat/Main.fs b/src/FSharp.MetadataFormat/Main.fs index dd9b5fa54..1a23c0e37 100755 --- a/src/FSharp.MetadataFormat/Main.fs +++ b/src/FSharp.MetadataFormat/Main.fs @@ -526,13 +526,21 @@ module Reader = KeyValuePair(k, html) ] Comment.Create(blurb, full, sections) - let readXmlComment (urlMap : IUrlHolder) (doc : XElement) = + let findCommand = (function + | String.StartsWithWrapped ("[", "]") (ParseCommand(k, v), rest) -> + Some (k, v) + | _ -> None) + + let readXmlComment (urlMap : IUrlHolder) (doc : XElement) (cmds: IDictionary<_, _>)= let full = new StringBuilder() let rec readElement (e : XElement) = Seq.iter (fun (x : XNode) -> if x.NodeType = XmlNodeType.Text then - full.Append((x :?> XText).Value) |> ignore + let text = (x :?> XText).Value + match findCommand text with + | Some (k,v) -> cmds.Add(k,v) + | None -> full.Append(text) |> ignore elif x.NodeType = XmlNodeType.Element then let elem = x :?> XElement match elem.Name.LocalName with @@ -690,15 +698,11 @@ module Reader = Log.verbf "Could not find documentation for '%s'! (You can ignore this message when you have not written documentation for this member)" xmlSig dict[], Comment.Empty | Some el -> + let cmds = new System.Collections.Generic.Dictionary<_, _>() if ctx.MarkdownComments then let sum = el.Element(XName.Get "summary") let value = if sum = null then el.Value else sum.Value let lines = removeSpaces value - let cmds = new System.Collections.Generic.Dictionary<_, _>() - let findCommand = (function - | String.StartsWithWrapped ("[", "]") (ParseCommand(k, v), rest) -> - Some (k, v) - | _ -> None) let text = lines |> Seq.filter (findCommand >> (function | Some (k, v) -> @@ -712,8 +716,7 @@ module Reader = |> (addMissingLinkToTypes ctx) cmds :> IDictionary<_, _>, readMarkdownComment doc else - let cmds = new System.Collections.Generic.Dictionary<_, _>() - cmds :> IDictionary<_, _>, readXmlComment ctx.UrlMap el + cmds :> IDictionary<_, _>, readXmlComment ctx.UrlMap el cmds let readComment ctx xmlSig = readCommentAndCommands ctx xmlSig |> snd From 2c6a6ef4b066af176936e1164ad4fa7f7fb52c10 Mon Sep 17 00:00:00 2001 From: Matthias Dittrich Date: Thu, 17 Dec 2015 18:58:11 +0100 Subject: [PATCH 8/8] fix failing test. --- src/FSharp.MetadataFormat/Main.fs | 47 ++++++++++++++++++------------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/src/FSharp.MetadataFormat/Main.fs b/src/FSharp.MetadataFormat/Main.fs index 1a23c0e37..dec1b019b 100755 --- a/src/FSharp.MetadataFormat/Main.fs +++ b/src/FSharp.MetadataFormat/Main.fs @@ -698,25 +698,34 @@ module Reader = Log.verbf "Could not find documentation for '%s'! (You can ignore this message when you have not written documentation for this member)" xmlSig dict[], Comment.Empty | Some el -> - let cmds = new System.Collections.Generic.Dictionary<_, _>() - if ctx.MarkdownComments then - let sum = el.Element(XName.Get "summary") - let value = if sum = null then el.Value else sum.Value - let lines = removeSpaces value - let text = - lines |> Seq.filter (findCommand >> (function - | Some (k, v) -> - cmds.Add(k, v) - false - | _ -> true)) |> String.concat "\n" - let doc = - Literate.ParseMarkdownString - ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), - formatAgent=ctx.FormatAgent, compilerOptions=ctx.CompilerOptions ) - |> (addMissingLinkToTypes ctx) - cmds :> IDictionary<_, _>, readMarkdownComment doc - else - cmds :> IDictionary<_, _>, readXmlComment ctx.UrlMap el cmds + let sum = el.Element(XName.Get "summary") + match sum with + | null when String.IsNullOrEmpty el.Value -> + dict[], Comment.Empty + | null -> + dict[], (Comment.Create ("", el.Value, [])) + | sum -> + let lines = removeSpaces sum.Value + let cmds = new System.Collections.Generic.Dictionary<_, _>() + + if ctx.MarkdownComments then + let text = + lines |> Seq.filter (findCommand >> (function + | Some (k, v) -> + cmds.Add(k, v) + false + | _ -> true)) |> String.concat "\n" + let doc = + Literate.ParseMarkdownString + ( text, path=Path.Combine(ctx.AssemblyPath, "docs.fsx"), + formatAgent=ctx.FormatAgent, compilerOptions=ctx.CompilerOptions ) + |> (addMissingLinkToTypes ctx) + cmds :> IDictionary<_, _>, readMarkdownComment doc + else + lines + |> Seq.choose findCommand + |> Seq.iter (fun (k, v) -> cmds.Add(k,v)) + cmds :> IDictionary<_, _>, readXmlComment ctx.UrlMap el cmds let readComment ctx xmlSig = readCommentAndCommands ctx xmlSig |> snd