diff --git a/.gitignore b/.gitignore index 4a9f6aef6..937dec896 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,4 @@ src/Common/AssemblyInfo.?s tests/FSharp.Literate.Tests/output1/ .vscode/ .DS_Store +tests/FSharp.Literate.Tests/output2/ diff --git a/FSharp.Formatting.sln b/FSharp.Formatting.sln index 9788ba162..225b55405 100644 --- a/FSharp.Formatting.sln +++ b/FSharp.Formatting.sln @@ -48,60 +48,62 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "reference", "reference", "{ misc\templates\reference\type.cshtml = misc\templates\reference\type.cshtml EndProjectSection EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Formatting.Markdown", "src\FSharp.Formatting.Markdown\FSharp.Formatting.Markdown.fsproj", "{C44C1C05-599A-40DD-9590-465EAB8960C5}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Formatting.Markdown", "src\FSharp.Formatting.Markdown\FSharp.Formatting.Markdown.fsproj", "{C44C1C05-599A-40DD-9590-465EAB8960C5}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Formatting.CodeFormat", "src\FSharp.Formatting.CodeFormat\FSharp.Formatting.CodeFormat.fsproj", "{341EBF32-D470-4C55-99E9-55F14F7FFBB1}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Formatting.CodeFormat", "src\FSharp.Formatting.CodeFormat\FSharp.Formatting.CodeFormat.fsproj", "{341EBF32-D470-4C55-99E9-55F14F7FFBB1}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Formatting.ApiDocs", "src\FSharp.Formatting.ApiDocs\FSharp.Formatting.ApiDocs.fsproj", "{BC4946BA-2724-4524-AC50-DFC49EE154A1}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Formatting.ApiDocs", "src\FSharp.Formatting.ApiDocs\FSharp.Formatting.ApiDocs.fsproj", "{BC4946BA-2724-4524-AC50-DFC49EE154A1}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Formatting.Literate", "src\FSharp.Formatting.Literate\FSharp.Formatting.Literate.fsproj", "{65E6D541-0486-4383-B619-5CFC5D2BA2F0}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Formatting.Literate", "src\FSharp.Formatting.Literate\FSharp.Formatting.Literate.fsproj", "{65E6D541-0486-4383-B619-5CFC5D2BA2F0}" EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "FSharp.Formatting.CSharpFormat", "src\FSharp.Formatting.CSharpFormat\FSharp.Formatting.CSharpFormat.csproj", "{9AB3650B-CC24-4404-A175-A573DA928475}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "fsdocs-tool", "src\fsdocs-tool\fsdocs-tool.fsproj", "{D30F7F2B-A4E3-4A07-A1BD-ED3EB21768F8}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "fsdocs-tool", "src\fsdocs-tool\fsdocs-tool.fsproj", "{D30F7F2B-A4E3-4A07-A1BD-ED3EB21768F8}" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{8D44B659-E9F7-4CE4-B5DA-D37CDDCD2525}" ProjectSection(SolutionItems) = preProject tests\commonmark_spec.json = tests\commonmark_spec.json EndProjectSection EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.CodeFormat.Tests", "tests\FSharp.CodeFormat.Tests\FSharp.CodeFormat.Tests.fsproj", "{5DEBD769-D86E-4E14-ABF1-373CA91BFAA2}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.CodeFormat.Tests", "tests\FSharp.CodeFormat.Tests\FSharp.CodeFormat.Tests.fsproj", "{5DEBD769-D86E-4E14-ABF1-373CA91BFAA2}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Literate.Tests", "tests\FSharp.Literate.Tests\FSharp.Literate.Tests.fsproj", "{C22A18AB-6C54-48B4-AAC5-892499E93D4D}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Literate.Tests", "tests\FSharp.Literate.Tests\FSharp.Literate.Tests.fsproj", "{C22A18AB-6C54-48B4-AAC5-892499E93D4D}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Markdown.Tests", "tests\FSharp.Markdown.Tests\FSharp.Markdown.Tests.fsproj", "{07DE4905-050C-4378-A039-F1EF7E1F309D}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Markdown.Tests", "tests\FSharp.Markdown.Tests\FSharp.Markdown.Tests.fsproj", "{07DE4905-050C-4378-A039-F1EF7E1F309D}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.ApiDocs.Tests", "tests\FSharp.ApiDocs.Tests\FSharp.ApiDocs.Tests.fsproj", "{D2EC3D6A-35C0-4445-A9CB-AA18B12B6350}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.ApiDocs.Tests", "tests\FSharp.ApiDocs.Tests\FSharp.ApiDocs.Tests.fsproj", "{D2EC3D6A-35C0-4445-A9CB-AA18B12B6350}" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "TestProjects", "TestProjects", "{4AE0198D-EDE5-40B0-A5CD-FC7B6F891D94}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FsLib1", "tests\FSharp.ApiDocs.Tests\files\FsLib1\FsLib1.fsproj", "{AD192375-D530-40FB-A4E9-380C74CBB771}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FsLib1", "tests\FSharp.ApiDocs.Tests\files\FsLib1\FsLib1.fsproj", "{AD192375-D530-40FB-A4E9-380C74CBB771}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FsLib2", "tests\FSharp.ApiDocs.Tests\files\FsLib2\FsLib2.fsproj", "{768FD0E0-5CF7-4AF0-98C9-4B848F9AFB62}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FsLib2", "tests\FSharp.ApiDocs.Tests\files\FsLib2\FsLib2.fsproj", "{768FD0E0-5CF7-4AF0-98C9-4B848F9AFB62}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "TestLib1", "tests\FSharp.ApiDocs.Tests\files\TestLib1\TestLib1.fsproj", "{86326769-3D0B-423F-AD28-A194B34318D6}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "TestLib1", "tests\FSharp.ApiDocs.Tests\files\TestLib1\TestLib1.fsproj", "{86326769-3D0B-423F-AD28-A194B34318D6}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "TestLib2", "tests\FSharp.ApiDocs.Tests\files\TestLib2\TestLib2.fsproj", "{48EFFECF-ECB0-4DF3-A704-B56AB07557BF}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "TestLib2", "tests\FSharp.ApiDocs.Tests\files\TestLib2\TestLib2.fsproj", "{48EFFECF-ECB0-4DF3-A704-B56AB07557BF}" +EndProject +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "TestLib3", "tests\FSharp.ApiDocs.Tests\files\TestLib3\TestLib3.fsproj", "{52B949AA-A3F7-4894-B713-804BAEB71118}" EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "csharpSupport", "tests\FSharp.ApiDocs.Tests\files\csharpSupport\csharpSupport.csproj", "{DA7BA2FA-447E-41F3-88D9-00CF3E052E2C}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "crefLib1", "tests\FSharp.ApiDocs.Tests\files\crefLib1\crefLib1.fsproj", "{A0C8DD00-BD08-48D6-B257-5A838E5DA819}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "crefLib1", "tests\FSharp.ApiDocs.Tests\files\crefLib1\crefLib1.fsproj", "{A0C8DD00-BD08-48D6-B257-5A838E5DA819}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "crefLib2", "tests\FSharp.ApiDocs.Tests\files\crefLib2\crefLib2.fsproj", "{55728B9D-1EDE-4A40-B439-1EB0B3F77B72}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "crefLib2", "tests\FSharp.ApiDocs.Tests\files\crefLib2\crefLib2.fsproj", "{55728B9D-1EDE-4A40-B439-1EB0B3F77B72}" EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "crefLib3", "tests\FSharp.ApiDocs.Tests\files\crefLib3\crefLib3.csproj", "{08029B28-A5EA-42DB-AB4E-9C6BA9EF9441}" EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "crefLib4", "tests\FSharp.ApiDocs.Tests\files\crefLib4\crefLib4.csproj", "{98624699-1B2F-4636-A3F7-EC72343CB2FD}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Formatting.Common", "src\FSharp.Formatting.Common\FSharp.Formatting.Common.fsproj", "{91BAD90E-BF3B-4646-A1A7-1568F8F25075}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Formatting.Common", "src\FSharp.Formatting.Common\FSharp.Formatting.Common.fsproj", "{91BAD90E-BF3B-4646-A1A7-1568F8F25075}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Formatting.TestHelpers", "tests\FSharp.Formatting.TestHelpers\FSharp.Formatting.TestHelpers.fsproj", "{0B552F94-33FE-4037-9C17-1EB2A885F263}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Formatting.TestHelpers", "tests\FSharp.Formatting.TestHelpers\FSharp.Formatting.TestHelpers.fsproj", "{0B552F94-33FE-4037-9C17-1EB2A885F263}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "AttributesTestLib", "tests\FSharp.ApiDocs.Tests\files\AttributesTestLib\AttributesTestLib.fsproj", "{B266D118-15AE-4BE6-809E-E9E30CE5C62F}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "AttributesTestLib", "tests\FSharp.ApiDocs.Tests\files\AttributesTestLib\AttributesTestLib.fsproj", "{B266D118-15AE-4BE6-809E-E9E30CE5C62F}" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{4089E333-3857-4771-B209-5673EF4EEDA3}" EndProject -Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "FSharp.Formatting", "src\FSharp.Formatting\FSharp.Formatting.fsproj", "{CB78F0EA-8005-4735-A02C-B86CEDC29D85}" +Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharp.Formatting", "src\FSharp.Formatting\FSharp.Formatting.fsproj", "{CB78F0EA-8005-4735-A02C-B86CEDC29D85}" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "sidebyside", "sidebyside", "{C3E359B5-DB2D-4AA4-A08C-77BAA0E94D21}" ProjectSection(SolutionItems) = preProject @@ -193,6 +195,10 @@ Global {48EFFECF-ECB0-4DF3-A704-B56AB07557BF}.Debug|Any CPU.Build.0 = Debug|Any CPU {48EFFECF-ECB0-4DF3-A704-B56AB07557BF}.Release|Any CPU.ActiveCfg = Release|Any CPU {48EFFECF-ECB0-4DF3-A704-B56AB07557BF}.Release|Any CPU.Build.0 = Release|Any CPU + {52B949AA-A3F7-4894-B713-804BAEB71118}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {52B949AA-A3F7-4894-B713-804BAEB71118}.Debug|Any CPU.Build.0 = Debug|Any CPU + {52B949AA-A3F7-4894-B713-804BAEB71118}.Release|Any CPU.ActiveCfg = Release|Any CPU + {52B949AA-A3F7-4894-B713-804BAEB71118}.Release|Any CPU.Build.0 = Release|Any CPU {DA7BA2FA-447E-41F3-88D9-00CF3E052E2C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {DA7BA2FA-447E-41F3-88D9-00CF3E052E2C}.Debug|Any CPU.Build.0 = Debug|Any CPU {DA7BA2FA-447E-41F3-88D9-00CF3E052E2C}.Release|Any CPU.ActiveCfg = Release|Any CPU @@ -267,6 +273,7 @@ Global {C7804F57-7FC6-4CF6-BDF6-127D6F9EBEA6} = {312E452A-1068-4804-89E7-0AFBAD5F885F} {188DC91F-2202-4495-ACD2-542D7C30364E} = {C7804F57-7FC6-4CF6-BDF6-127D6F9EBEA6} {FAD5C374-4748-4A3D-A435-FFA425916F3A} = {312E452A-1068-4804-89E7-0AFBAD5F885F} + {52B949AA-A3F7-4894-B713-804BAEB71118} = {4AE0198D-EDE5-40B0-A5CD-FC7B6F891D94} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {76F121F8-70E0-49FB-9ADF-C7B660C0EB67} diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 83d5e94b6..d94b8a827 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,3 +1,7 @@ +## 17.2.1 + +* Fix support for `` [#786](https://github.com/fsprojects/FSharp.Formatting/issues/786) + ## 17.2.0 * Resolve markdown links in raw html [#769](https://github.com/fsprojects/FSharp.Formatting/issues/769) diff --git a/docs/apidocs.fsx b/docs/apidocs.fsx index 10bde06a5..cb1eba3dd 100644 --- a/docs/apidocs.fsx +++ b/docs/apidocs.fsx @@ -85,7 +85,7 @@ In addition, you may also use the [Recommended XML doc extensions for F# documen * `` giving documentation for the enclosing namespace -* `` to exclude from XML docs +* `` to exclude from XML docs * `` to give a category for an entity or member. An optional `index` attribute can be specified to help sort the list of categories. @@ -169,6 +169,63 @@ type GenericClass2<'T>() = /// and let referringFunction2 () = "result" +(** +### Classic XMl Doc Comments: Excluding APIs from the docs + +If you want to exclude modules or functions from the API docs you can use the `` tag. +It needs to be set on a separate triple-slashed line, and can either appear on its own or as part +of an existing `` (for example, you may wish to hide existing documentation while it's in progress). +The `` tag can be the first or last line in these cases. + +Some examples: +*) + +/// +module BottleKids1 = + let a = 42 + +// Ordinary comment +/// +module BottleKids2 = + let a = 43 + +/// +/// BottleKids3 provides improvements over BottleKids2 +module BottleKids3 = + let a = 44 + +/// BottleKids4 implements several new features over BottleKids3 +/// +module BottleKids4 = + let a = 45 + +/// +/// +/// BottleKids5 is all you'll ever need in terms of bottles or kids. +/// +module BottleKids5 = + let a = 46 + +(** + +Note that the comments for `BottleKids3` (and `BottleKids4`) will generate a warning. This is because +the `` tag will be parsed as part of the `summary` text, and so the documentation generator +can't be completely sure you meant to exclude the item, or whether it was a valid part of the documentation. +It will assume the exclusion was intended, but you may want to use explicit `` tags to remove +the warning. + +The warning will be of the following format: +``` +Warning: detected "" in text of "" for "M:YourLib.BottleKids4". Please see https://fsprojects.github.io/FSharp.Formatting/apidocs.html#Classic-XML-Doc-Comments +``` +You will find that `[omit]` also works, but is considered part of the Markdown syntax and is +deprecated for XML Doc comments. This will also produce a warning, such as this: + +``` +The use of `[omit]` and other commands in XML comments is deprecated, please use XML extensions, see https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1031-xmldoc-extensions.md +``` + +*) (** ## Go to Source links @@ -177,21 +234,25 @@ let referringFunction2 () = "result" This is normally done automatically based on the following settings: +```xml https://github.com/... ... git +``` If your source is not built from the same project where you are building documentation then you may need these settings: +```xml ... -- the URL for the root of the source ... -- the root soure folder at time of build +``` It is assumed that `sourceRepo` and `sourceFolder` have synchronized contents. ## Markdown Comments -You can use Markdown instead of XML in `///` comments. If you do, you should set `` in +You can use Markdown instead of XML in `///` comments. If you do, you should set `true` in your F# project file. > Note: Markdown Comments are not supported in all F# IDE tooling. @@ -242,7 +303,7 @@ module Foo3 = ### Markdown Comments: Excluding APIs from the docs If you want to exclude modules or functions from the API docs you can use the `[omit]` tag. -It needs to be set on a separate tripple-slashed line, but it could be either the first or the last: +It needs to be set on a separate triple-slashed line, but it could be either the first or the last: Example as last line: *) @@ -290,3 +351,18 @@ ApiDocs.GenerateHtml( template = Path.Combine(root, "templates", "template.html"), substitutions = [] ) + + +(** +## Rebasing Links + +The `root` parameter is used for the base of page and image links in the generated documentation. By default it is derived from the project's `` property. + +In some instances, you may wish to override the value for `root` (perhaps for local testing). To do this, you can use the command-line argument `--parameters root `. + +For example: + + [lang=text] + dotnet fsdocs build --output public/docs --parameters root ../ + +*) \ No newline at end of file diff --git a/src/FSharp.Formatting.ApiDocs/GenerateModel.fs b/src/FSharp.Formatting.ApiDocs/GenerateModel.fs index db4d83746..61fdaa015 100644 --- a/src/FSharp.Formatting.ApiDocs/GenerateModel.fs +++ b/src/FSharp.Formatting.ApiDocs/GenerateModel.fs @@ -614,7 +614,7 @@ type ApiDocEntity member x.RequiresQualifiedAccess: bool = rqa /// All nested modules and types - member x.NestedEntities: ApiDocEntity list = nested + member x.NestedEntities: ApiDocEntity list = nested |> List.filter (fun e -> not e.Exclude) /// Values and functions of the module member x.ValuesAndFuncs: ApiDocMember list = vals @@ -2260,22 +2260,31 @@ module internal SymbolReader = | Some el -> let sum = el.Element(XName.Get "summary") - match sum with - | null when String.IsNullOrEmpty el.Value -> cmds, ApiDocComment.Empty, None - | null -> - // We let through XML comments without a summary tag. It's not clear - // why as all XML coming through here should be from F# .XML files - // and should have the tag. It may be legacy of previously processing un-processed - // XML in raw F# source. + // sum can be null with null/empty el.Value when an non-"" XML element appears + // as the only '///' documentation command: + // + // 1. + // // Not triple-slash ccomment + // /// + // + // 2. + // /// + if isNull sum then let doc, nsels = readXmlCommentAsHtmlAux false ctx.UrlMap el cmds let nsdocs = readNamespaceDocs ctx.UrlMap nsels cmds, doc, nsdocs - | sum -> - if ctx.MarkdownComments then - readMarkdownCommentAndCommands ctx sum.Value el cmds - else - readXmlCommentAndCommands ctx sum.Value el cmds + else if ctx.MarkdownComments then + readMarkdownCommentAndCommands ctx sum.Value el cmds + else + if sum.Value.Contains("\" in text of \"\" for \"%s\". Please see https://fsprojects.github.io/FSharp.Formatting/apidocs.html#Classic-XML-Doc-Comments" + xmlSig + + readXmlCommentAndCommands ctx sum.Value el cmds /// Reads XML documentation comments and calls the specified function /// to parse the rest of the entity, unless [omit] command is set. @@ -2841,7 +2850,7 @@ type ApiDocModel internal (substitutions, collection, entityInfos, root, qualify member _.Collection: ApiDocCollection = collection /// The full list of all entities - member _.EntityInfos: ApiDocEntityInfo list = entityInfos + member _.EntityInfos: ApiDocEntityInfo list = entityInfos |> List.filter (fun info -> not info.Entity.Exclude) /// The root URL for the entire generation, normally '/' member _.Root: string = root diff --git a/tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs b/tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs index c4456c8b1..280e02652 100644 --- a/tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs +++ b/tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs @@ -127,6 +127,63 @@ let generateApiDocs (libraries: string list) (format: OutputFormat) useMdComment do FSharp.Formatting.TestHelpers.enableLogging () + +[] +[] +let ``ApiDocs excludes items`` (format: OutputFormat) = + let library = testBin "TestLib3.dll" |> fullpath + + let files = generateApiDocs [ library ] format false "TestLib3" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldContainText "Returns unit" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldNotContainText "shouldBeOmitted" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldNotContainText "shouldBeExcluded1" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldNotContainText "shouldBeExcluded2" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldNotContainText "shouldBeExcluded3" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldNotContainText "shouldBeExcluded4" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldNotContainText "shouldBeExcluded5" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldNotContainText "shouldBeExcluded6" + + files.[(sprintf "fslib-partiallydocumented.%s" format.Extension)] + |> shouldNotContainText "shouldBeExcluded7" + + // We can only expect a warning for "wishItWasExcluded1" & "WishItWasExcluded2" + + files.ContainsKey(sprintf "fslib-partiallydocumented-notdocumented1.%s" format.Extension) + |> shouldEqual false + + files.ContainsKey(sprintf "fslib-partiallydocumented-notdocumented2.%s" format.Extension) + |> shouldEqual false + + files.ContainsKey(sprintf "fslib-partiallydocumented-notdocumented3.%s" format.Extension) + |> shouldEqual false + + files.ContainsKey(sprintf "fslib-undocumentedmodule.%s" format.Extension) + |> shouldEqual false + + files.ContainsKey(sprintf "test-dom.%s" format.Extension) |> shouldEqual true + + files.ContainsKey(sprintf "test-dom-domaction.%s" format.Extension) + |> shouldEqual false + + files.[(sprintf "test-dom.%s" format.Extension)] + |> shouldNotContainText "DomAction" + [] [] let ``ApiDocs works on sample Deedle assembly`` (format: OutputFormat) = @@ -915,6 +972,7 @@ let ``ApiDocs process XML comments in two sample F# assemblies`` (format: Output files.[(sprintf "fslib-nested-submodule.%s" format.Extension)] |> shouldContainText "Very nested field" + [] [] let ``ApiDocs highlights code snippets in Markdown comments`` (format: OutputFormat) = @@ -1054,9 +1112,9 @@ let ``ApiDocs omit works without markdown`` (format: OutputFormat) = let files = generateApiDocs [ library ] format false "FsLib2_omit" - // Actually, the thing gets generated it's just not in the index + // Omitted items shouldn't have generated a file files.ContainsKey(sprintf "fslib-test_omit.%s" format.Extension) - |> shouldEqual true + |> shouldEqual false [] [] diff --git a/tests/FSharp.ApiDocs.Tests/FSharp.ApiDocs.Tests.fsproj b/tests/FSharp.ApiDocs.Tests/FSharp.ApiDocs.Tests.fsproj index 0d8ab7122..60a249ed1 100644 --- a/tests/FSharp.ApiDocs.Tests/FSharp.ApiDocs.Tests.fsproj +++ b/tests/FSharp.ApiDocs.Tests/FSharp.ApiDocs.Tests.fsproj @@ -26,6 +26,7 @@ + diff --git a/tests/FSharp.ApiDocs.Tests/files/TestLib3/DOM.fs b/tests/FSharp.ApiDocs.Tests/files/TestLib3/DOM.fs new file mode 100644 index 000000000..e705e68c9 --- /dev/null +++ b/tests/FSharp.ApiDocs.Tests/files/TestLib3/DOM.fs @@ -0,0 +1,15 @@ +/// +/// DOM low-level helper functions +/// +module Test.DOM + +/// +type DomAction = + | Append + | Replace of int + | Nothing + +/// +let edit (_: DomAction) = () + +let build () = () diff --git a/tests/FSharp.ApiDocs.Tests/files/TestLib3/Library3.fs b/tests/FSharp.ApiDocs.Tests/files/TestLib3/Library3.fs new file mode 100644 index 000000000..bd2bf6362 --- /dev/null +++ b/tests/FSharp.ApiDocs.Tests/files/TestLib3/Library3.fs @@ -0,0 +1,61 @@ +namespace FsLib + +module PartiallyDocumented = + + /// Should be omitted (but will generated a warning) + /// [omit] + let shouldBeOmitted () = () + + /// + /// + /// Should be excluded + /// + let shouldBeExcluded1 () = () + + /// + /// Should be excluded + /// + /// + let shouldBeExcluded2 () = () + + // Should be excluded + /// + let shouldBeExcluded3 () = () + + /// + // Should be excluded + let shouldBeExcluded4 () = () + + /// + let shouldBeExcluded5 () = () + + /// + /// This triple-'/' comment auto-creates a summary element with the exclude tag escaped into its text + let shouldBeExcluded6 () = () + + /// This triple-'/' comment auto-creates a summary element with the exclude tag escaped into its text + /// + let shouldBeExcluded7 () = () + + /// + /// Returns unit + /// + let returnUnit () = () + + /// + /// Should be excluded + /// + /// + module NotDocumented1 = + let a = 10 + + /// + module NotDocumented2 = + let a = 10 + + /// This triple-'/' comment auto-creates a summary element with the exclude tag escaped into its text + /// + module NotDocumented3 = + let a = 10 + + let x = 10 diff --git a/tests/FSharp.ApiDocs.Tests/files/TestLib3/TestLib3.fsproj b/tests/FSharp.ApiDocs.Tests/files/TestLib3/TestLib3.fsproj new file mode 100644 index 000000000..9cfdaae8f --- /dev/null +++ b/tests/FSharp.ApiDocs.Tests/files/TestLib3/TestLib3.fsproj @@ -0,0 +1,14 @@ + + + + netstandard2.1 + ..\bin\$(Configuration) + + + + + + + + + diff --git a/tests/FSharp.ApiDocs.Tests/files/TestLib3/UndocumentedModule.fs b/tests/FSharp.ApiDocs.Tests/files/TestLib3/UndocumentedModule.fs new file mode 100644 index 000000000..8ab0f5eb4 --- /dev/null +++ b/tests/FSharp.ApiDocs.Tests/files/TestLib3/UndocumentedModule.fs @@ -0,0 +1,3 @@ +module private FsLib.UndocumentedModule + +let pi () = 3.141 diff --git a/tests/FSharp.ApiDocs.Tests/files/TestLib3/paket.references b/tests/FSharp.ApiDocs.Tests/files/TestLib3/paket.references new file mode 100644 index 000000000..0a1dca0be --- /dev/null +++ b/tests/FSharp.ApiDocs.Tests/files/TestLib3/paket.references @@ -0,0 +1,2 @@ +FSharp.Compiler.Service +FSharp.Core