Cách tham chiếu các lớp và phương thức chung trong tài liệu xml


198

Khi viết tài liệu xml bạn có thể sử dụng <see cref="something">something</see>, tất nhiên là có tác dụng. Nhưng làm thế nào để bạn tham chiếu một lớp hoặc một phương thức với các kiểu chung?

public class FancyClass<T>
{
  public string FancyMethod<K>(T value) { return "something fancy"; }
}

Nếu tôi định viết tài liệu xml ở đâu đó, làm thế nào tôi có thể tham khảo lớp ưa thích? Làm thế nào tôi có thể tham khảo a FancyClass<string>? Còn phương pháp thì sao?

Ví dụ trong một lớp khác tôi muốn cho người dùng biết rằng tôi sẽ trả về một thể hiện của FancyClass<int>. Làm thế nào tôi có thể làm cho một điều cref thấy cho điều đó?

Câu trả lời:


257

Để tham khảo phương pháp:

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.

3
Cảm ơn câu trả lời đó! Nó thực sự bị thiếu từ trang của MSDN trên <see>: msdn.microsoft.com/en-us/l
Library / acd0tfbe.aspx

6
Tôi thực sự tin rằng nó cũng hoạt động trong các công cụ VS2010 mà bạn cần chỉ ra số lượng đối số chung, ví dụ: "FancyClass 1{T}.FancyMethod1 {K} (T)"
Stephen Drew

Không chắc ý của bạn về điều đó. Tôi chưa bao giờ phải thêm chúng, và nó luôn làm việc cho tôi. Bạn có một ví dụ cụ thể nơi nó không hoạt động? Nếu vậy, xin vui lòng gửi nó ở đâu đó (hoặc thậm chí tự cung cấp câu trả lời.)
Lasse V. Karlsen

@Lasse, vui lòng xem câu trả lời và bình luận của Steve bên dưới. Câu trả lời của bạn không bao gồm các chú giải công cụ Intellisense chính xác.
Jakub Januszkiewicz

43
/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

BTW, nó đã có mặt trong tài liệu MSDN của .Net Framework 2.03.0 , nhưng nó không xuất hiện trong phiên bản 3.5


4
Điều gì về một ví dụ đặc biệt của T? như chuỗi? Có lẽ không thể?
Svish

Ý anh là gì? Bạn không thể khai báo một phiên bản cụ thể, vì vậy bạn cũng không thể tham khảo nó.
Lasse V. Karlsen

Nếu một phương thức ví dụ chỉ trả về Danh sách <chuỗi> chẳng hạn. Nhưng không quan trọng :)
Svish

7
Có, tôi cũng đang tự hỏi ... chia sẻ lại tiếng cười khúc khích khi viết FancyClass {chuỗi} nhưng không phải khi viết FancyClass {String} ...
thinkbeforecoding

6
Lý do cho quan sát trên của "Think Before Coding" là vì nó không hoạt động với các bí danh c #. Ví dụ: bạn cần sử dụng Int32thay vì int, Singlethay vì floatvv (Đặt thông tin này ở đây trong trường hợp có ai khác vấp phải điều này)
AnorZaken 13/03/2015

27

TL; DR:

"Làm thế nào tôi sẽ tham khảo FancyClass<T>?"

   /// <see cref="FancyClass{T}"/>

"Thế còn FancyClass<T>.FancyMethod<K>(T value)?"

   /// <see cref="FancyClass{T}.FancyMethod{K}(T)"/>

"Làm thế nào tôi có thể tham khảo một FancyClass<string>?"

   /// <see cref="SomeType.SomeMethod(FancyClass{string})"/>
   /// <see cref="FancyClass{T}"/> whose generic type argument is <see cref="string"/>

Mặc dù bạn có thể tham chiếu một phương thức có chữ ký bao gồm FancyClass<string>(ví dụ như một loại tham số), bạn không thể tham chiếu trực tiếp một loại chung chung như vậy. Ví dụ thứ hai hoạt động xung quanh giới hạn đó. (Điều này được nhìn thấy, ví dụ như trên trang giới thiệu MSDN cho System.String.Concat(IEnumerable<string>)phương thức tĩnh ). :

crefQuy tắc nhận xét tài liệu XML :

  • Bao quanh danh sách tham số loại chung với dấu ngoặc nhọn{} thay vì <>dấu ngoặc nhọn. Điều này cho phép bạn thoát khỏi cái sau &lt;&gt;- hãy nhớ rằng, các nhận xét tài liệu là XML!

  • Nếu bạn bao gồm một tiền tố (chẳng hạn nhưT: cho các loại, M:cho các phương thức, P:cho các thuộc tính, F:cho các trường), trình biên dịch sẽ không thực hiện bất kỳ xác thực tham chiếu nào, mà chỉ cần sao chép crefgiá trị thuộc tính thẳng vào đầu ra XML của tài liệu. Vì lý do này, bạn sẽ phải sử dụng cú pháp "chuỗi ID" đặc biệt áp dụng trong các tệp đó: luôn sử dụng mã định danh đủ điều kiện và sử dụng backticks để tham chiếu các tham số loại chung ( `nvề loại, ``ntrên phương thức).

  • Nếu bạn bỏ qua tiền tố , các quy tắc đặt tên ngôn ngữ thông thường sẽ được áp dụng: bạn có thể bỏ các không gian tên có usingcâu lệnh và bạn có thể sử dụng các từ khóa loại ngôn ngữ như intthay vì System.Int32. Ngoài ra, trình biên dịch sẽ kiểm tra tham chiếu cho chính xác.

crefBảng cheat nhận xét tài liệu XML :

namespace X
{
    using System;

    /// <see cref="I1"/>  (or <see cref="X.I1"/> from outside X)
    /// <see cref="T:X.I1"/>
    interface I1
    {
        /// <see cref="I1.M1(int)"/>  (or <see cref="M1(int)"/> from inside I1)
        /// <see cref="M:X.I1.M1(System.Int32)"/>
        void M1(int p);

        /// <see cref="I1.M2{U}(U)"/>
        /// <see cref="M:X.I1.M2``1(``0)"/>
        void M2<U>(U p);

        /// <see cref="I1.M3(Action{string})"/>
        /// <see cref="M:X.I1.M3(System.Action{System.String})"/>
        void M3(Action<string> p);
    }

    /// <see cref="I2{T}"/>
    /// <see cref="T:X.I2`1"/>
    interface I2<T>
    {
        /// <see cref="I2{T}.M1(int)"/>
        /// <see cref="M:X.I2`1.M1(System.Int32)"/>
        void M1(int p);

        /// <see cref="I2{T}.M2(T)"/>
        /// <see cref="M:X.I2`1.M2(`0)"/>
        void M2(T p);

        /// <see cref="I2{T}.M3{U}(U)"/>
        /// <see cref="M:X.I2`1.M3``1(``0)"/>
        void M3<U>(U p);
    }
}

Làm thế nào để chỉ giới thiệu Tmột phần?
nawfal

4
Hình:<typeparamref name="T"/>
nawfal

21

Không có câu trả lời nào cho thấy cho đến nay làm việc hoàn toàn cho tôi. ReSharper sẽ không chuyển đổi thẻ xem thành Ctrlliên kết + có thể nhấp (ví dụ hình ảnh ở đây) trừ khi nó hoàn toàn giải quyết.

Nếu phương thức trong OP nằm trong một không gian tên được gọi Test, liên kết được giải quyết hoàn toàn với phương thức được hiển thị sẽ là:

<see cref="M:Test.FancyClass`1.FancyMethod``1(`0)"/>

Vì bạn có thể giải quyết được, chỉ nên có một backtick trước số lượng tham số loại lớp, sau đó hai backticks trước số lượng tham số loại phương thức, sau đó các tham số là tham số được lập chỉ mục bằng 0 với số lượng backticks thích hợp.

Vì vậy, chúng ta có thể thấy rằng FancyClasscó một tham số loại lớp, FancyMethodcó một tham số loại và một đối tượng của FancyClassloại tham số sẽ được truyền cho phương thức.

Như bạn có thể thấy rõ hơn trong ví dụ này:

namespace Test
{
    public class FancyClass<A, B>
    {
        public void FancyMethod<C, D, E>(A a, B b, C c, D d, E e) { }
    }
}

Liên kết trở thành:

M:Test.FancyClass`2.FancyMethod``3(`0,`1,``0,``1,``2)

Hoặc "Class với các thông số hai loại trong đó có một phương pháp với ba thông số loại nơi các thông số phương pháp là ClassType1, ClassType2, MethodType1, MethodType2, MethodType3"


Một ghi chú bổ sung, tôi đã không tìm thấy tài liệu này ở bất cứ đâu và tôi không phải là thiên tài, trình biên dịch đã nói với tôi tất cả điều này. Tất cả những gì bạn phải làm là tạo một dự án thử nghiệm, kích hoạt tài liệu XML , sau đó chèn mã bạn muốn tạo ra một liên kết và đặt phần bắt đầu của một nhận xét tài liệu XML vào nó ( ///):

namespace Test
{
    public class FancyClass<T>
    {
        ///
        public string FancyMethod<K>(T value) { return "something fancy"; }
    }

    public class Test
    {
        public static void Main(string[] args) { }
    }
}

Sau đó, xây dựng dự án của bạn và tài liệu XML được xuất ra bao gồm liên kết trong phần tử doc-> members-> memberdưới thuộc tính name:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Test</name>
    </assembly>
    <members>
        <member name="M:Test.FancyClass`1.FancyMethod``1(`0)">

        </member>
    </members>
</doc>

3
Điều này sẽ nhận được nhiều upvote hơn, đặc biệt là do mẹo để tìm ký hiệu chính xác, mà không phải trải qua thử và sai. Kudos người đàn ông của tôi
Peter

10

Thêm từ câu trả lời của Lasse và TBC:

/// <see cref="T:FancyClass`1{T}"/> for more information.

/// <see cref="M:FancyClass`1{T}.FancyMethod`1{K}(T)"/> for more information.

cũng sẽ cung cấp các chú giải công cụ một cách chính xác, trong khi phiên bản của chúng kết xuất nó với các dấu ngoặc nhọn.


2
Sử dụng <see cref = "System.Collections.Generic.List 1{T}"/>** causes a build-time warning: **XML comment on 'Blah' has syntactically incorrect cref attribute 'System.Collections.Generic.List1 <T> - bạn có quan tâm đến việc giải thích cách người ta nên sử dụng cái này không?
Jakub Januszkiewicz

2
Xin chào Jakub, Điều này thực sự không có hiệu quả. Cách duy nhất tôi cũng có thể khiến các chú giải công cụ hoạt động chính xác là <see cref = "T: <fullTypeName>` 1 {T} "/>.
Stephen Drew

2
OK, tôi đã nhận được một phần. Nếu bản thân phương thức không chung chung (như trong Danh sách <T> .Add ()), thì phương thức này hoạt động: <see cref = "M: System.Collections.Generic.List`1 {T} .Add (T)" /> .
Jakub Januszkiewicz

1
Dường như không làm việc cho tôi. Tôi có <see cref = "M: System.Collections.Generic.List`1 {T}" /> trong tiêu đề nhận xét cho một phương thức mở rộng chung mà tôi đã viết (chuyển đổi một ArrayList thành Danh sách <T>) nhưng ReSharper gắn cờ nó là một lỗi cú pháp và IntelliSense chỉ hiển thị nguyên văn. VS 2010 / R # 6.1.37.86
Mike Loux

8
Aha! Tôi đã có thể làm cho <see cref = "T: System.Collections.Generic.List`1" /> " hoạt động. Vì vậy, sử dụng T: thay vì các dấu ngoặc nhọn đã thực hiện thủ thuật. Nó mở rộng ra không gian tên đầy đủ, và mẹo không hoạt động nếu bạn không bao gồm không gian tên, vì vậy nó không hoàn hảo, nhưng nó sẽ làm được.
Mike Loux

5
/// Here we discuss the use of <typeparamref name="TYourExcellentType"/>.
/// <typeparam name="TYourExcellentType">Your exellent documentation</typeparam>

3
Lưu ý rằng các câu trả lời khác bao gồm cách tham chiếu một lớp chung, câu trả lời này chỉ cho bạn cách tự tham chiếu loại tham số, đây là điều mà tôi đang muốn làm.
17:30

Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.