Есть ли причина, по которой методы в контроллерах ASP.NET MVC не документированы в XML? - PullRequest
Новая
       7

Есть ли причина, по которой методы в контроллерах ASP.NET MVC не документированы в XML?

3 голосов
/ 25 февраля 2011

Я огромный фанат XML-документации в .NET.

Однако я могу честно сказать, что никогда не видел учебник или проект, где, например, у нас была разметка, подобная этой: 

/// <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: Как работать с сущностями со многими дочерними сущностями? ?

Ответы [ 2 ]

8 голосов
/ 25 февраля 2011

XML документация хороша, когда необходимо документировать общедоступный API для внешних сторон, использующих его. Контроллеры, на мой взгляд, не попадают в эту категорию.

Также в соответствии с тонкими контроллерами, они должны быть самоочевидны в отношении того, что они делают, особенно с такими метаданными атрибутов, как HttpPost и HttpGet.

Предполагаете ли вы, что третье лицо будет использовать ваши контроллеры в качестве API?

2 голосов
/ 25 февраля 2011

Я обычно документирую свои действия контроллера с кратким описанием того, что должно делать это действие, например: 

/// <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 . Я все еще верю, что такого рода документация добавляет ценность:

  • В нем разъясняется, что класс / метод / параметр делает на простом английском
  • In подтверждает, что ничего особенного не происходит (в отличие от того, кто просто не удосужился написать документацию).

Обратите внимание, что я не документирую возвращаемое значение, поскольку я абсолютно ничего не могу сказать о нем.

Вам также нужно учитывать, что этот пример невероятно надуманен - ​​возможно, некоторые параметры представляют собой сериализованные данные JSON или что отрицательное значение означает нечто совершенно иное. Мой взгляд на документацию XML заключается в том, что вы должны либо ничего не документировать, либо документировать все (независимо от того, насколько это очевидно). Если только половина ваших методов документирована, вы никогда не сможете сказать, является ли это, потому что это совершенно очевидно, или если разработчик был просто слишком ленив - также учтите, что цель метода может быть не столь очевидна для других, как для вас.

Например, я не пытаюсь писать документацию для обработчиков событий (раньше, но комментарии всегда были одинаковыми).

...