Documenting your code with XML documentation has the huge benefit of a structured preview and concise description in the automated API reference:
Current triple slash documentation
/// This function takes a collection of x values performs a log transform
let myFunction (xData: seq<float>) = xData |> Seq.map log
Improved XML documentation
/// <summary>This function takes a collection of x values performs a log transform</summary>
/// <remarks>Note, that the log of 0 is -infinity</remarks>
/// <param name="xData">collection of values to be transformed</param>
/// <returns>A collection of log transformed values</returns>
/// <example>
/// <code>
/// // e.g. abundance data for ABC
/// let xData = vector [|1.;2.;3.;4.;5.;6.|]
///
/// // Apply the log transform to the xData
/// myFunction xData
/// </code>
/// </example>
let myFunction (xData: seq<float>) = xData |> Seq.map log
go from top to bottom and extend the documentation at any point you can see (modules, types, members, functions)
try identify and write meaningful code examples within the xml comments
build the repository yourself and check if the comments work as intended when hovering over the functions/modules...
Hints (click to expand if you need additional pointers)
- To be able to contribute to this library you'll need
- an GitHub account
- an IDE like Visual Studio Community or Visual Studio Code
- [dotnet 6 sdk](https://dotnet.microsoft.com/en-us/download)
- to build the binaries yourself follow the [instructions](https://fslab.org/FSharp.Stats/#Installation)
- while working on the [FSharp.Stats documentation](https://fslab.org/FSharp.Stats/) (any file within https://github.com/fslaborg/FSharp.Stats/tree/developer/docs) you can navigate to the project folder with a prompt of your choice and use the command `./build watchdocs`
- unit tests can be executed via `./build runtests`
Description
Documenting your code with XML documentation has the huge benefit of a structured preview and concise description in the automated API reference:
Current triple slash documentation
Improved XML documentation
References
>
for > and<
for <)Hints (click to expand if you need additional pointers)
- To be able to contribute to this library you'll need - an GitHub account - an IDE like Visual Studio Community or Visual Studio Code - [dotnet 6 sdk](https://dotnet.microsoft.com/en-us/download) - to build the binaries yourself follow the [instructions](https://fslab.org/FSharp.Stats/#Installation) - while working on the [FSharp.Stats documentation](https://fslab.org/FSharp.Stats/) (any file within https://github.com/fslaborg/FSharp.Stats/tree/developer/docs) you can navigate to the project folder with a prompt of your choice and use the command `./build watchdocs` - unit tests can be executed via `./build runtests`Progress