Question

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

我的老师希望我们写xml文档，我当然会学习。但是从侧面看，我读了很多源代码，其中包括.md文件，例如在GitHub上在线提供文档。

我应该专注于学习XML文档方法还是应该专注于其他事情？有人可以向我暗示一个正确的方向，以便在何处阅读有关此内容的良好而可靠的指南吗？

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

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

许多专业的F＃项目都使用FSharp.Formatting library，这使您可以在“ XML文档”注释（即///注释）中编写Markdown而不是XML。如果您只是在学习F＃，设置FSharp.Formatting可能会有些棘手，所以我的建议是使用类似ProjectScaffold template的东西：克隆https://github.com/fsprojects/ProjectScaffold存储库，然后运行{ {1}}（如果您使用的是Windows，则为build.sh），并回答一些问题，例如项目名称。（然后，您应该将ProjectScaffold中的文件夹重命名为与项目名称匹配的文件夹）。从那时起，运行build.cmd或build.sh将在您的项目中使用build.cmd注释，通过FSharp.Formatting运行它们，并将其转换为良好的HTML文档（使其联机）< em>和用于其他工具的优秀XML文档。

当然，现在您应该遵循老师的指示。但是同时，您还应该熟悉FSharp.Formatting（为此，我强烈建议使用诸如ProjectScaffold之类的工具，而不是尝试自己进行设置）。然后，一旦知道它有效，就可以问老师是否可以使用FSharp.Formatting和Markdown并将其显示给他。

Answer 2

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

您可以将markdown用作文档，不应将xml用于创建文档。

XML或Markdown文档？从哪里开始作为新程序员

2 个答案: