XML or Markdown documentation? Where to start as a new programmer

user_9891285 0
Viewed 386

I am a new programmer and I am learning to program with F# and currently learning about the documentation part. The F# built-in documentation syntax follows C# (XML).

My teacher wants us to write xml documentations, which I will of course learn. But on the side I read a lot of source codes which includes .md files instead, and have documentation online on GitHub for example.

Should I focus on learning the XML documentation method or should I focus on something else? Can someone hint me in a good direction on where to read a good and reliable guide on this?

Below is a short XML documentation (my first) I tried to write just documenting how a simple sum-function is working. Any kind of input would be greatly appreciated as well!

///<summary>Get the sum of numbers to n and with n included</summary>
///<example>
///     The code:
///   <code>
///         let sum(n : int) = 
/// 
///              let mutable result: int = 0
///              let mutable i     : int = 0
/// 
///              while i < n do
/// 
///                  i <- i + 1
///                  result <- result + i
/// 
///          result 
///   </code>
///</example>
///
///<remarks>Input:
///   <code>
///         printfn "Sum af 1 + 2 + ... + n = %i" (sum(4)) 
///  </code>   
///</remarks>
///<returns>Sum af 1 + 2 + ... + n = 10</returns>
///<param name="n"> Natural number, n > 0 n <> real numbers </param>




let sum(n : int) = 

    let mutable result: int = 0
    let mutable i     : int = 0

    while i < n do

        i <- i + 1
        result <- result + i

    result // result of sum of n

printfn "Sum af 1 + 2 + ... + n = %i" (sum(4))
markdown documentation f# xml c#
2 Answers

A lot of professional F# projects use the FSharp.Formatting library, which allows you to write Markdown instead of XML in the "XML documentation" comments (that is, the /// comments). It can be a little bit tricky to set up FSharp.Formatting if you're just learning F#, so my recommendation would be to use something like the ProjectScaffold template: you clone the https://github.com/fsprojects/ProjectScaffold repository, then run build.sh (or build.cmd if you're on Windows) and answer a few questions like the name of your project. (And then you should rename the folder from ProjectScaffold to something that matches the name of your project). From that point on, running build.sh or build.cmd will take the /// comments in your project, run them through FSharp.Formatting, and convert them to good HTML documentation (to put online) and good XML documentation for use in other tools.

For now, of course, you should follow your teacher's instructions. But at the same time, you should also get familiar with FSharp.Formatting (and I highly recommend using something like ProjectScaffold for that purpose rather than trying to set it up on your own). Then once you know it works, you can ask your teacher whether using FSharp.Formatting and Markdown would be acceptable, and show him the results.

user_23145320
user_52408890
Related