ASP.NET MVC 控制器中的方法似乎没有被 XML 记录是否有原因？

Question

我非常喜欢 .NET 中的 XML 文档。

但是，我可以诚实地说，我从未见过教程或项目，例如，我们有这样的标记：

/// <summary>
/// dummy text
/// </summary>
/// <returns>blah</returns>
public ActionResult LogOff() {
    FormsService.SignOut();

    return RedirectToAction("Index", "Home");
}

而不是：

// **************************************
// URL: /Account/LogOff
// **************************************

public ActionResult LogOff() {
    FormsService.SignOut();

    return RedirectToAction("Index", "Home");
}

这有什么特殊原因吗？我是唯一一个想要记录我的控制器方法的人吗？

编辑1：

虽然大多数控制器方法似乎很简单，但在说这个问题时详细说明情况如何： MVC：如何与具有多个子实体的实体一起工作？ ?

Answer 1

当需要为使用公共 API 的外部方记录公共 API 时，XML 文档非常有用。在我看来，控制器不属于这一类。

同样与苗条控制器一致，它们应该对其所做的事情是不言自明的，特别是对于诸如 HttpPost 和 HttpGet 之类的属性元数据。

您是否设想第三方使用您的控制器作为 API？

Answer 2

我通常会用简短的​​描述来记录我的控制器操作，例如该操作的用途，例如：

/// <summary>
/// Controller for viewing and updating the jobs list.
/// </summary>
public class JobsController : Controller
{
    /// <summary>
    /// Displays a list of all jobs for a given site.
    /// </summary>
    /// <param name="siteId">Id of the site to view jobs for.</param>
    public ActionResult Index(string siteId);

    /// <summary>
    /// Displays a detail view of a single job.
    /// </summary>
    /// <param name="id">Id of the job to view.</param> 
    public ActionResult Detail(string id);
}

它与我的其他类的 xml 文档不太一样，因为这些类永远不会直接使用，因此它的更多文档网站/页面行为比其他任何事情都重要。也就是说，我发现描述操作的作用和参数是什么很有用，这里是一个很好的地方。

请注意，我没有包含路径 - 不仅因为如果路径发生更改，则信息已过时，而且还因为通过查看路由映射应该显而易见路径将是什么。

更新/回复评论：

这种文档可能看起来完全没有意义，因为无论如何，这些类几乎都是自我描述的，但是在正确结构化代码中命名良好的方法这通常是 XML 的情况无论如何，文档。然而，我仍然相信此类文档会增加价值：

• 它用简单的英语阐明了类/方法/参数的作用
• ，确认没有发生任何特殊情况（而不是有人只是懒得编写文档）。

请注意，我不记录返回值，因为我绝对没有什么可以说的。

您还需要考虑到这个示例是非常人为的 - 某些参数可能是 JSON 序列化数据，或者负值意味着完全不同的东西。我对 XML 文档的看法是，要么不记录任何内容，要么应该记录所有内容（无论多么明显）。如果只有一半的方法被记录下来，那么你永远无法判断它是否是因为它完全显而易见，或者开发人员是否只是太懒了 - 还要考虑到方法的目的对其他人来说可能不像对你那么明显。

例如，我懒得为事件处理程序编写文档（我曾经这样做过，但注释总是完全相同）。