如何在C＃中向类，方法，属性等添加文档工具提示？

Not sure if I'm even calling this right but I wanted to start adding some documentation to my classes, methods, properties, etc. I know this is probably super obvious but I never really learned it. I'm not sure where to start.

我不确定我是否正确地调用了这个,但我想开始在我的类,方法,属性等中添加一些文档。我知道这可能是非常明显但我从未真正学过它。我不知道从哪里开始。

Just to clarify whenever you roll over a class (or method, property, etc.) it shows a tooltip in Visual Studio with some documentation on that specific method.

只是为了澄清每当你翻转一个类(或方法,属性等)时,它会在Visual Studio中显示一个工具提示,其中包含有关该特定方法的一些文档。

class Microsoft.Phone.BackgroundAudio.BackgroundAudioPlayer
Provides background access to audio playback functionality such as play, pause, fast-forward, and rewind.

class Microsoft.Phone.BackgroundAudio.BackgroundAudioPlayer提供对音频播放功能的后台访问,如播放,暂停,快进和快退。

What is that called and how can I implement this in my C# application?

那叫什么,我怎样才能在我的C#应用​​程序中实现它?

3 个解决方案

#1

You can use /// or GhostDoc

您可以使用///或GhostDoc

Edit:

In first case you'll get

在第一种情况下,你会得到

/// <summary>
/// 
/// </summary>
class A
{
    /// <summary>
    /// 
    /// </summary>
    public A() { }

    /// <summary>
    /// 
    /// </summary>
    public int Property { get; set; }

    /// <summary>
    /// 
    /// </summary>
    /// <param name="obj"></param>
    public void Method(object obj) { }
}

In second

/// <summary>
/// 
/// </summary>
class B
{

    /// <summary>
    /// Initializes a new instance of the <see cref="B"/> class.
    /// </summary>
    public B() { }

    /// <summary>
    /// Gets or sets the property.
    /// </summary>
    /// <value>
    /// The property.
    /// </value>
    public int Property { get; set; }

    /// <summary>
    /// Methods the specified obj.
    /// </summary>
    /// <param name="obj">The obj.</param>
    public void Method(object obj) { }
}

#2

Just above your class, method or property, type /// then press return. This will generate the documentation template for you.

在您的类,方法或属性上方,键入///然后按return。这将为您生成文档模板。

Forgot to answer the other part of your question: this is known as XML Documentation Comments and there is a substantial amount of information about this in MSDN.

忘记回答问题的其他部分:这称为XML文档注释,在MSDN中有大量有关此内容的信息。

#3

What you are referring to is called XML documentation or XML-doc.

您所指的是XML文档或XML-doc。

XML-doc is performed on a class, field, property, event or method using three forward-slashes (///), followed by XML-formatted meta-information about the class or its member.

XML-doc使用三个正斜杠(///)对类,字段,属性,事件或方法执行,后跟关于类或其成员的XML格式的元信息。

VS will help you generate and format these comments with built-in IntelliSense support for XML comments, but there is a free tool called GhostDoc that will automatically generate the full XML-doc template, and it's even "smart" enough in some cases to try to guess a basic description for various elements of the documentation.

VS将通过内置的IntelliSense支持XML注释来帮助您生成和格式化这些注释,但有一个名为GhostDoc的免费工具将自动生成完整的XML-doc模板,在某些情况下甚至可以“智能”地尝试猜测文档各种元素的基本描述。

Here's a basic example of XML documentation:

这是XML文档的基本示例:

/// <summary>
/// Defines the behavior of a class following the Repository pattern for data access 
/// with basic atomic operation control.
/// </summary>
/// <typeparam name="TRest">An interface derived from IDomainObject that describes domain objects 
/// that can be retrieved or saved by this Repository.</typeparam>
public interface IRepository<TRest> : IDisposable where TRest : IDomainObject
{
    /// <summary>
    /// Begins a new unit of work to be performed atomically by the Repository.
    /// </summary>
    /// <returns>A token class representing the unit of work.</returns>
    IUnitOfWork BeginUnitOfWork();

    /// <summary>
    /// Commits all work performed under the specified unit of work.
    /// </summary>
    /// <param name="unitOfWork">The unit of work.</param>
    void CommitUnitOfWork(IUnitOfWork unitOfWork);

    /// <summary>
    /// Rolls back the specified unit of work.
    /// </summary>
    /// <param name="unitOfWork">The unit of work.</param>
    void RollBackUnitOfWork(IUnitOfWork unitOfWork);

    /// <summary>
    /// Saves the specified domain object to the data source controlled by the repository.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="domainObject">The domain object.</param>
    /// <param name="unitOfWork">The unit of work.</param>
    void Save<T>(T domainObject, IUnitOfWork unitOfWork) where T : class, TRest;

    /// <summary>
    /// Begins a Linq query for a specific object type, to be performed against the Repository's data source.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="unitOfWork">The unit of work.</param>
    /// <returns>An IQueryable representing the query to be performed.</returns>
    IQueryable<T> QueryFor<T>(IUnitOfWork unitOfWork) where T : class, TRest;

    /// <summary>
    /// Performs the specified Action using a new unit of work, with commits and rollbacks as necessary.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="func">The Action to perform. The lambda or named method must accept an IUnitOfWork as a parameter.</param>
    /// <param name="commit">if set to <c>true</c>, commit the unit of work.</param>
    void PerformInNewUnitOfWork<T>(Action<IUnitOfWork> func, bool commit = false);

    /// <summary>
    /// Performs the specified Func using a new unit of work, with commits and rollbacks as necessary.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="func">The function to evaluate. The lambda or named method must accept an IUnitOfWork as a parameter.</param>
    /// <returns>A single object of the generic type, returned by the function.</returns>
    /// <param name="commit">if set to <c>true</c>, commit the unit of work.</param>
    T PerformInNewUnitOfWork<T>(Func<IUnitOfWork, T> func, bool commit = false) where T : class, TRest;

    /// <summary>
    /// Performs the specified Func using a new unit of work, with commits and rollbacks as necessary.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="func">The Function to evaluate. The lambda or named method must accept an IUnitOfWork as a parameter.</param>
    /// <returns>An enumerable set of objects of the generic type, returned by the function.</returns>
    /// <param name="commit">if set to <c>true</c>, commit the unit of work.</param>
    IEnumerable<T> PerformInNewUnitOfWork<T>(Func<IUnitOfWork, IEnumerable<T>> func, bool commit = false) where T : class, TRest;

    /// <summary>
    /// Attaches the specified domain object to the current Unit of Work, allowing operations to be performed on it.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="domainObject">The domain object.</param>
    /// <param name="unitOfWork">The unit of work.</param>
    void Attach<T>(T domainObject, IUnitOfWork unitOfWork) where T : class, TRest;

    /// <summary>
    /// Detaches the specified domain object to the current Unit of Work.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="domainObject">The domain object.</param>
    /// <param name="unitOfWork">The unit of work.</param>
    void Detach<T>(T domainObject, IUnitOfWork unitOfWork) where T : class, TRest;

    /// <summary>
    /// Refreshes the specified collection of persistent elements with the most recent persisted data.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="elements">The list of elements to refresh.</param>
    /// <param name="unitOfWork">The Unit of Work under which to perform the operation.</param>
    void Refresh<T>(IList<T> elements, IUnitOfWork unitOfWork) where T : class, TRest;

    /// <summary>
    /// Deletes the specified domain object from the data store. 
    /// Usually performs a physical delete; logical deletes are most often done through updates.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="domainObject">The domain object to delete.</param>
    /// <param name="unitOfWork">The unit of work under which to perform the operation.</param>
    void Delete<T>(T domainObject, IUnitOfWork unitOfWork) where T : class, TRest;
}