标签: code-documentation

在C#中使用XML注释,我可以记录一个方法可能抛出异常:

<exception cref="FooException">Thrown if foo is invalid.</exception>

但是,如果某个方法exception的XML文档中没有标记,则这可能意味着以下两种情况之一:

1. 作者彻底测试了该方法,确保它永远不会抛出异常,并希望通过不添加exception标记来记录这一事实.
2. 作者并不关心记录异常,因此这种方法可能会抛出任何东西.

根据我的经验,第二种情况通常就是这样.那么问题是:

如何明确记录方法永远不会抛出异常？

到目前为止,我提出的最好的方法是简单地在方法中提及它summary,例如"此方法不会抛出异常".但我想知道是否有更正式的方式表达这一点,就像throw()在C++中一样(尽管这可能是一个不好的例子).

我正在寻找类似 GhostDoc for VS Code (C#) 的东西，但没有成功。有谁知道什么吗？

我只找到了一个“旧的”类似 VS 的扩展，它使 XML 注释在您键入“///”时可用，但这不是我正在寻找的。

我在Kotlin官方参考中找到了记录Kotlin代码的页面.

然而,我无法找到如何突出文档的某些部分,例如,将其标记为斜体或粗体.

我是Kotlin的新手,来自Java,以前只使用过我们使用的JavaDoc <i>和<b>HTML标签来突出文档中的部分.

是否有工具可以检查文档字符串中列出的参数是否与函数调用的签名匹配？它应该能够处理 numpy 风格的文档字符串。我经常使用 R CMD CHECK，它可以发现 R 中的文档/代码不匹配，这非常有帮助。如果 Python 中有类似的东西那就太好了，但我还没有找到任何东西。

我正在搜索.NET Core的源代码，因为我想看看核心类是如何实现的。比如我想看看string类是怎么写的。有人可以给我指出 .NET Core 的源代码吗？

.NET 参考资源中有一个很棒的 .NET Framework 在线浏览工具 。.NET Core 是否存在类似的东西？

PS：我尝试在 GitHub 上查找但找不到。

此 GitHub 链接允许下载 SDK 源代码，但缺少 String.cs 等类

您的.NET源代码文档中有多少是太多了？

一些背景:我继承了一个很大的代码库,我已经在SO上发布了一些其他问题.这个代码库的一个"特性"是God Class,一个包含大约3000行代码的单个静态类,包含几十个静态方法.这是一个从一切Utilities.CalculateFYBasedOnMonth()要Utilities.GetSharePointUserInfo()到Utilities.IsUserIE6().这些都是不需要重写的好代码,只需重构成一组适当的库.我已经计划好了.

由于这些方法正在进入一个新的业务层,我在这个项目中的角色是为其他开发人员准备系统以进行维护,我正在考虑可靠的代码文档.虽然这些方法都具有良好的内联注释,但它们并不都具有XML注释形式的良好(或任何)代码doco.使用GhostDoc和Sandcastle(或文档X)的组合,我可以创建一些非常好的HTML文档并将其发布到SharePoint,这将使开发人员更多地了解代码的作用,而无需浏览代码本身.

随着代码中文档量的增加,导航代码变得越困难.我开始怀疑XML注释是否会使代码更难以维护,比如说//comment每个方法更简单.

这些示例来自Document X示例:

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer …

我们将ReSharper 6.0与StyleCop一起用于ReSharper.

虽然我们使用StyleCop规则,成员必须有文档头,但我们不希望ReSharper的代码清理工具为我们生成文档头,因为它们不可避免地会变成垃圾.糟糕的文档标题比没有标题更糟糕,因为它们的更新可能性不如首先添加.

我们尝试在ReSharper => Options => Tools => StyleCop中关闭"将文本插入文档和文件头"设置,但是当您重新启动visual studio时,它会自行重置.

有什么想法我们如何阻止代码清理为我们创建文档标题？

我正在使用XML和Sandcastle帮助文件生成器记录C#代码以生成HtmlHelp1帮助文件.我已经SyntaxFilters在Sandcastle项目上设置了属性,CSharp因为我只想生成与C#相关的代码语法.

我正在使用,<see langword="[langword]" />如下所示:

<see langword="null" />
<see langword="true" />
<see langword="false" />

正如我将SyntaxFilters属性设置为CSharp我期望将上述标记转换为等效的C#关键字,如下所示:

null
true
false

而是将它们转换为Visual Basic的等效关键字,如下所示:

Nothing
True
False

有没有办法用适当的C#关键字而不是Visual Basic关键字替换这些标签,或者我根本不使用see标签？

我为我的问题的简单性道歉,但我试图使用Appledocs生成文档(https://github.com/tomaz/appledoc#quick-install)

我不确定如何设置它.我这样做的方式是:

• 我克隆了github repo,然后在终端中使用安装脚本(我使用appledocs --help确认这个)安装appledocs .

但是,现在我如何实际使用这个,因为我在xcode中有我的项目:

• 如何生成文档文件
• 它在哪里生成？

我是 Powershell 的新手，据我所知，它没有像 Python 中的 PEP8/PEP484 这样的东西。我从 Microsoft找到了这份文档，并从 Posh Code 找到了这份第三方指南。我写了以下函数：

function Invoke-Authenticate {

  [CmdletBinding()]
  param (
      [Parameter(Mandatory)]
      [string] 
      # IP address of the OME server
      $Ip,

      [Parameter(Mandatory)]
      # Credentials for the OME server
      [pscredential] $Credentials
  )

  $SessionUrl  = "https://$($IpAddress)/api/SessionService/Sessions"
  $Type        = "application/json"
  $UserDetails = @{"UserName"=$Credentials.username;"Password"=$Credentials.GetNetworkCredential().password;
                   "SessionType"="API"} | ConvertTo-Json
  $Headers     = @{}

  try {
    $SessResponse = Invoke-WebRequest -Uri $SessionUrl -Method Post -Body $UserDetails -ContentType $Type `
                                      -SkipCertificateCheck
    if ($SessResponse.StatusCode -eq 200 -or $SessResponse.StatusCode -eq 201) {
      # …