XML 还是 Markdown 文档？新程序员从哪里开始

Question

我是一名新程序员，我正在学习使用 F# 进行编程，目前正在学习文档部分。 F# 内置文档语法遵循 C# (XML)。

老师要我们写xml文档，我当然要学。但另一方面，我阅读了很多源代码，其中包括 .md 文件，并在 GitHub 上提供了在线文档。

我应该专注于学习 XML 文档方法还是应该专注于其他事情？有人能给我一个好的方向，告诉我在哪里可以阅读这方面的好而可靠的指南吗？

下面是一个简短的 XML 文档（我的第一个），我试图写的只是记录一个简单的求和函数是如何工作的。任何类型的输入也将不胜感激！

///<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))

Answer 1

我认为学习降价的最佳资源是：https://guides.github.com/features/mastering-markdown/。

您可以使用 markdown 作为文档，xml 不应该用来创建文档。

Answer 2

很多专业的 F# 项目使用 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 存储库，然后是运行 build.sh（或者 build.cmd，如果你在 Windows）和回答几个问题，比如你的项目名称。（然后您应该将文件夹从 ProjectScaffold 重命名为与您的项目名称相匹配的名称）。从那时起，运行ning build.sh 或 build.cmd 将在您的项目中获取 /// 评论，运行通过 FSharp.Formatting，并转换HTML 文档（放在网上）和用于其他工具的 XML 文档。

现在，当然，您应该听从老师的指示。但与此同时，您还应该熟悉 FSharp.Formatting（我 强烈建议 为此目的使用 ProjectScaffold 之类的东西，而不是尝试自行设置） .然后一旦你知道它有效，你可以问你的老师使用 FSharp.Formatting 和 Markdown 是否可以接受，并向他展示结果。

XML 还是 Markdown 文档？新程序员从哪里开始

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

c#

xml

documentation

markdown

f#