fslaborg / FSharp.Stats

statistical testing, linear algebra, machine learning, fitting and signal processing in F#
https://fslab.org/FSharp.Stats/
Other
205 stars 54 forks source link

Added XML documentation structure #306

Closed simontreanor closed 9 months ago

simontreanor commented 9 months ago

281

Description

XML documentation structure added using regex in VSCode IDE.

Regex procedure (works for 99% of cases):

1) Merge multiline documentation comments into a single line with a line-break delimiter (iterate until exhausted) Find: ^(\s+/// )(\w.+)\n\1(.+) Replace: $1$2<br />$3

2) Create the standard XML comment structure, including the existing comment and params (one-off) Find: ///\s*(\w.+)\n((\s+)let (inline )?(\w\w*) ((((\w\w*)|\([^)]+\))\s*)+)) Replace: /// <summary>$1</summary>\n$3/// <remarks></remarks>\n$3/// <param name="$6"></param>\n$3/// <returns></returns>\n$3/// <example>\n$3/// <code>\n$3/// </code>\n$3/// </example>\n$2

3) Separate multiple parameters (iterate until exhausted) Find: (\s+/// )<param name="((\w\w*)|\([^)]+\)) ((((\w\w*)|\([^)]+\)) )+)"></param> Replace: $1<param name="$2"></param>\n$1<param name="$3"></param>

4) Remove any trailing spaces from params (one-off) Find: <param name="((\w\w*)|\([^)]+\)) "></param> Replace: <param name="$1"></param>

5) Remove type annotations from params (one-off) Find: <param name="\((.+?):[^"]+"></param> Replace: <param name="$1"></param>

[Required] please make sure you checked that

codecov-commenter commented 9 months ago

Codecov Report

Merging #306 (5fafaa1) into developer (1e680b1) will not change coverage. The diff coverage is n/a.

@@            Coverage Diff             @@
##           developer     #306   +/-   ##
==========================================
  Coverage      46.73%   46.73%           
==========================================
  Files            148      148           
  Lines          16225    16225           
  Branches        2196     2196           
==========================================
  Hits            7582     7582           
  Misses          7987     7987           
  Partials         656      656           
Files Coverage Δ
src/FSharp.Stats/AlgTypes.fs 29.48% <ø> (ø)
src/FSharp.Stats/Algebra/EVD.fs 0.00% <ø> (ø)
src/FSharp.Stats/Algebra/LinearAlgebra.fs 40.00% <ø> (ø)
...Sharp.Stats/Algebra/LinearAlgebraServiceManaged.fs 27.89% <ø> (ø)
src/FSharp.Stats/Array.fs 3.16% <ø> (ø)
src/FSharp.Stats/ConfidenceInterval.fs 100.00% <ø> (ø)
src/FSharp.Stats/Correlation.fs 1.06% <ø> (ø)
src/FSharp.Stats/DistanceMetrics.fs 40.90% <ø> (ø)
src/FSharp.Stats/Distributions/Bandwidth.fs 3.27% <ø> (ø)
src/FSharp.Stats/Distributions/Continuous/Beta.fs 45.20% <ø> (ø)
... and 61 more
bvenn commented 9 months ago

Awesome work! Thanks for this complex regex patterns. Now there are no excuses in not updating the comments while working on existing functions :grin:

I've fixed some issues, when the parameter name was within the /// description. Furthermore the name of private functions were considered as parameters. Private functions in general need no extensive XML-description, but I fixed the cases where it happened