Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes for <exclude/> support, with tests and docs. #787

Merged
merged 13 commits into from
Jan 14, 2023
Merged
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,4 @@ src/Common/AssemblyInfo.?s
tests/FSharp.Literate.Tests/output1/
.vscode/
.DS_Store
tests/FSharp.Literate.Tests/output2/
6 changes: 6 additions & 0 deletions FSharp.Formatting.sln
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,8 @@ Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "TestLib1", "tests\FSharp.Ap
EndProject
Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "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}"
davedawkins marked this conversation as resolved.
Show resolved Hide resolved
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}"
Expand Down Expand Up @@ -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
Expand Down
73 changes: 72 additions & 1 deletion docs/apidocs.fsx
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,63 @@ type GenericClass2<'T>() =
/// and <see cref="M:TheNamespace.GenericClass2`1.GenericMethod``1(`0,``0)" />
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 `<exclude/>` 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 `<summary>` (for example, you may wish to hide existing documentation while it's in progress).
The `<exclude/>` tag can be the first or last line in these cases.

Some examples:
*)

/// </exclude>
davedawkins marked this conversation as resolved.
Show resolved Hide resolved
module BottleKids1 =
let a = 42

// Ordinary comment
/// </exclude>
module BottleKids2 =
let a = 43

/// </exclude>
/// BottleKids3 provides improvements over BottleKids2
module BottleKids3 =
let a = 44

/// BottleKids4 implements several new features over BottleKids3
/// </exclude>
module BottleKids4 =
let a = 45

/// </exclude>
/// <summary>
/// BottleKids5 is all you'll ever need in terms of bottles or kids.
/// </summary>
module BottleKids5 =
let a = 46

(**

Note that the comments for `BottleKids3` (and `BottleKids4`) will generate a warning. This is because
the `<exclude/>` 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 treat it as an exclusion was intended, but you may want to use explicit `<summary>` tags to remove
the warning.

The warning will be of the following format:
```
Warning: detected "<exclude/>" in text of "<summary>" 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
Expand Down Expand Up @@ -242,7 +299,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:
*)
Expand Down Expand Up @@ -290,3 +347,17 @@ 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, and by default is derived from the project's `<PackageProjectUrl>` 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 <base>`.

For example:
```
% dotnet fsdocs build --output public/docs --parameters root ../
```
*)
2 changes: 1 addition & 1 deletion src/FSharp.Formatting.ApiDocs/GenerateHtml.fs
Original file line number Diff line number Diff line change
Expand Up @@ -707,7 +707,7 @@ type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) =
printfn " Generating %s" outFile
SimpleTemplating.UseFileAsSimpleTemplate(substitutions, templateOpt, outFile)

for info in model.EntityInfos do
for info in model.EntityInfos |> List.filter (fun info -> not info.Entity.Exclude) do
davedawkins marked this conversation as resolved.
Show resolved Hide resolved
let content = div [] (entityContent info)

let pageTitle = sprintf "%s (%s)" info.Entity.Name collectionName
Expand Down
2 changes: 1 addition & 1 deletion src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs
Original file line number Diff line number Diff line change
Expand Up @@ -447,7 +447,7 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
printfn " Generating %s" outFile
SimpleTemplating.UseFileAsSimpleTemplate(substitutions, templateOpt, outFile)

for info in model.EntityInfos do
for info in model.EntityInfos |> List.filter (fun info -> not info.Entity.Exclude) do
let content = MarkdownDocument(entityContent info, Map.empty)

let pageTitle = sprintf "%s (%s)" info.Entity.Name collectionName
Expand Down
26 changes: 25 additions & 1 deletion src/FSharp.Formatting.ApiDocs/GenerateModel.fs
Original file line number Diff line number Diff line change
Expand Up @@ -2261,12 +2261,30 @@ module internal SymbolReader =
let sum = el.Element(XName.Get "summary")

match sum with
davedawkins marked this conversation as resolved.
Show resolved Hide resolved
| null when String.IsNullOrEmpty el.Value -> cmds, ApiDocComment.Empty, None

// sum can be null with null/empty el.Value when an non-"<summary>" XML element appears
// as the only '///' documentation command:
//
// 1.
// // Not triple-slash ccomment
// /// <exclude/>
//
// 2.
// /// <exclude/>
//
// So, we need to let the 'null' case handle this to extract the <exclude> if it's there
//
// | null when String.IsNullOrEmpty el.Value ->
davedawkins marked this conversation as resolved.
Show resolved Hide resolved
// 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.
//
// 9-Jan-23: See comment above for at least one reason why we pass through here now
davedawkins marked this conversation as resolved.
Show resolved Hide resolved

let doc, nsels = readXmlCommentAsHtmlAux false ctx.UrlMap el cmds

let nsdocs = readNamespaceDocs ctx.UrlMap nsels
Expand All @@ -2275,6 +2293,12 @@ module internal SymbolReader =
if ctx.MarkdownComments then
readMarkdownCommentAndCommands ctx sum.Value el cmds
else
if sum.Value.Contains("<exclude") then
cmds.["exclude"] <- ""
printfn
"Warning: detected \"<exclude/>\" in text of \"<summary>\" 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
Expand Down
Loading