Как я могу переопределить сводный комментарий базового метода от дочерней реализации? - PullRequest
Новая
       38

Как я могу переопределить сводный комментарий базового метода от дочерней реализации?

0 голосов
/ 27 февраля 2012

Я использую SandCastle для документирования API, который я сейчас разрабатываю.При настройке конечных точек я определил следующий базовый класс: 

/// <summary>
/// The base class for all services operating in the API.
/// </summary>
/// <typeparam name="T">The type of object to be controlled via the given service</typeparam>
/// <typeparam name="TPrimaryKey">The type of the primary key for the object to be controlled via the given service</typeparam>
public abstract class BaseService<T, TPrimaryKey> : ServiceContracts.IBaseService<T, TPrimaryKey>
    where T : class
{
    /// <summary>
    /// Adds or updates the given item.
    /// </summary>
    /// <param name="item">The item to be added or updated.</param>
    public void AddOrUpdate(T item)
    {
        // perform setup / validation
        PerformAddOrUpdate(item);
        // perform teardown
    }

    protected abstract void PerformAddOrUpdate(T item);
}

У меня тогда будут различные сервисные внедрения, например: 

/// <summary>
/// Service that allows for <see cref="DataContracts.Product"/> records to be controlled via the API.
/// </summary>
public class ProductService : BaseService<Product, long?>, IProductService
{
    /// <summary>
    /// Creates or updates the given product record. 
    /// If a product with the item's Id exists, that record will be updated. 
    /// Otherwise, a new record will be created.
    /// </summary>
    /// <param name="item">The <see cref="DataContracts.Product"/> to be added or updated.</param>
    protected override void PerformAddOrUpdate(Product item)
    {
        throw new NotImplementedException();
    }
}

Теперь, когда я генерирую документацию,Я не хочу показывать защищенный метод (ы), потому что потребитель сервиса не должен интересоваться этими деталями реализации.Однако в сводке по ProductService.PerformAddOrUpdate(Product) есть информация, позволяющая звонящему узнать, когда произойдет добавление, а не по обновлению (т. Е. У него есть обобщенная сводная информация).

Можно ли выполнитьнапротив <inheritdoc />, поэтому, когда потребитель увидит AddOrUpdate, он получит документацию для дочернего класса PerformAddOrUpdate?

Заранее спасибо.

РЕДАКТИРОВАТЬ Пример документации, как она есть сейчас:

Пример документации

Мне бы хотелось, чтобы это описание (в настоящее время «Добавляет или обновляет данный элемент.») Извлекается из<summary> для PerformAddOrUpdate только для этого представления (поэтому каждый дочерний элемент будет отображать свой собственный <summary>, поскольку он будет находиться в пределах своей собственной области при переопределении).Если смотреть на BaseService напрямую, он должен показать <summary>, как сейчас.

...