วิธีอ้างอิงคลาสและเมธอดทั่วไปในเอกสารคู่มือ xml


198

เมื่อเขียนเอกสาร xml คุณสามารถใช้<see cref="something">something</see>งานได้แน่นอน แต่คุณจะอ้างอิงคลาสหรือวิธีที่มีประเภททั่วไปได้อย่างไร

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

ถ้าฉันจะเขียนเอกสาร xml ที่ไหนสักแห่งฉันจะอ้างอิงคลาสแฟนซีได้อย่างไร? ฉันจะอ้างอิงกได้FancyClass<string>อย่างไร วิธีการเกี่ยวกับอะไร?

FancyClass<int>ยกตัวอย่างเช่นในชั้นเรียนที่แตกต่างกันผมอยากที่จะให้ความรู้ผู้ใช้ว่าผมจะกลับมาตัวอย่างของ ฉันจะทำสิ่งที่เห็น cref สำหรับที่?

คำตอบ:


258

เพื่ออ้างอิงวิธีการ:

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

3
ขอบคุณสำหรับคำตอบ! ที่จริงแล้วมันหายไปจากหน้าของ MSDN ใน <see>: msdn.microsoft.com/en-us/library/acd0tfbe.aspx
joce

6
จริง ๆ แล้วฉันเชื่อว่ามันจะทำงานในคำแนะนำเครื่องมือ VS2010 คุณต้องระบุจำนวนของข้อโต้แย้งทั่วไปเช่น "FancyClass 1{T}.FancyMethod1 {K} (T)"
สตีเฟ่น Drew

ไม่แน่ใจว่าคุณหมายถึงอะไร ฉันไม่เคยต้องเพิ่มสิ่งเหล่านี้และมันได้ผลสำหรับฉันเสมอ คุณมีตัวอย่างเฉพาะที่ไม่สามารถใช้งานได้หรือไม่ ถ้าเป็นเช่นนั้นโปรดโพสต์ไว้ที่ใดที่หนึ่ง (หรือแม้กระทั่งให้คำตอบด้วยตัวเอง)
Lasse V. Karlsen

@ Lasse โปรดดูคำตอบและความคิดเห็นของ Steve ด้านล่าง คำตอบของคุณไม่ครอบคลุมคำแนะนำเครื่องมือ Intellisense ที่ถูกต้อง
Jakub Januszkiewicz

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

BTW มันมีอยู่ในเอกสาร MSDN ของ. Net Framework 2.0และ3.0แต่มันหายไปในเวอร์ชัน 3.5


4
สิ่งที่เกี่ยวกับตัวอย่างแบบ spesific ของ T? ชอบสตริง? อาจจะเป็นไปไม่ได้?
Svish

คุณหมายถึงอะไร คุณไม่สามารถประกาศรุ่นที่เฉพาะเจาะจงดังนั้นคุณจึงไม่สามารถอ้างอิงได้
Lasse V. Karlsen

ถ้าเมธอดตัวอย่างส่งคืน List <string> ตัวอย่างเท่านั้น แต่ :) ไม่สำคัญ
Svish

7
ใช่ฉันสงสัยด้วย ... resharpers squiggles เมื่อเขียน FancyClass {string} แต่ไม่ใช่เมื่อเขียน FancyClass {String} ...
thinkbeforecoding

6
เหตุผลสำหรับการสังเกตข้างต้นโดย "คิดก่อนรหัส" คือมันไม่ทำงานกับนามแฝง c # ตัวอย่างเช่นคุณต้องการที่จะใช้Int32แทนint, Singleแทนfloatฯลฯ(ใส่ข้อมูลที่นี่ในกรณีที่คนอื่นสะดุดกับเรื่องนี้)
AnorZaken

27

TL; DR:

"ฉันจะอ้างอิงได้FancyClass<T>อย่างไร"

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

"แล้วFancyClass<T>.FancyMethod<K>(T value)ไงล่ะ"

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

"ฉันจะอ้างอิงได้FancyClass<string>อย่างไร"

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

ในขณะที่คุณสามารถอ้างอิงวิธีการที่มีลายเซ็นรวมอยู่FancyClass<string>(เช่นประเภทพารามิเตอร์) แต่คุณไม่สามารถอ้างอิงประเภททั่วไปแบบปิดดังกล่าวได้โดยตรง ตัวอย่างที่สองทำงานรอบข้อ จำกัด นั้น (จะเห็นได้เช่นในหน้าการอ้างอิง MSDN สำหรับSystem.String.Concat(IEnumerable<string>)วิธีการแบบคงที่ ) :

crefกฎความคิดเห็นเอกสารคู่มือ XML :

  • ล้อมรอบรายการพารามิเตอร์ประเภททั่วไปด้วยเครื่องหมายปีกกา{}แทนที่จะเป็น<>วงเล็บเหลี่ยม สิ่งนี้ช่วยให้คุณไม่ต้องหลบหนีจากหลังในฐานะ&lt;และ&gt;- จำไว้ว่าการแสดงความคิดเห็นเอกสารเป็น XML!

  • หากคุณรวมคำนำหน้า (เช่นT:สำหรับประเภทM:สำหรับวิธีการP:สำหรับคุณสมบัติF:สำหรับฟิลด์) คอมไพเลอร์จะไม่ทำการตรวจสอบความถูกต้องของการอ้างอิงใด ๆ แต่เพียงคัดลอกcrefค่าคุณลักษณะตรงไปยังเอาท์พุท XML เอกสารคู่มือ ด้วยเหตุนี้คุณจะต้องใช้ไวยากรณ์ "สตริง ID"พิเศษที่ใช้กับไฟล์ดังกล่าว: ใช้ตัวระบุที่ผ่านการรับรองโดยสมบูรณ์และใช้ backticks เพื่ออ้างอิงพารามิเตอร์ประเภททั่วไป ( `nตามประเภท``nวิธีการ)

  • ถ้าคุณไม่ใช้คำนำหน้าภาษาปกติกฎการตั้งชื่อใช้: คุณสามารถวาง namespaces ที่มีusingคำสั่งและคุณสามารถใช้คำหลักประเภทของภาษาเช่นแทนint System.Int32คอมไพเลอร์จะตรวจสอบการอ้างอิงเพื่อความถูกต้อง

crefสูตรชีทแสดงความคิดเห็นเอกสาร 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);
    }
}

วิธีการอ้างอิงเพียงTส่วนหนึ่ง?
nawfal

4
คิดออก:<typeparamref name="T"/>
nawfal

21

ไม่มีคำตอบใดที่แสดงให้เห็นว่าใช้งานได้สมบูรณ์สำหรับฉัน ReSharper จะไม่แปลงแท็กดูเป็นCtrlลิงก์ + คลิกได้ (เช่นภาพที่นี่) เว้นแต่จะได้รับการแก้ไขอย่างสมบูรณ์

หากวิธีการใน OP อยู่ในเนมสเปซที่เรียกว่าTestลิงก์ที่ได้รับการแก้ไขอย่างสมบูรณ์ไปยังวิธีการที่แสดงจะเป็น:

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

ในขณะที่คุณสามารถออกกำลังกายได้ควรมี backtick เพียงอันเดียวก่อนจำนวนพารามิเตอร์ประเภทคลาสจากนั้น backticks สองตัวก่อนจำนวนพารามิเตอร์ชนิดเมธอดจากนั้นพารามิเตอร์คือพารามิเตอร์ zero-indexed ที่มีจำนวน backticks ที่เหมาะสม

ดังนั้นเราจะเห็นว่าFancyClassมีพารามิเตอร์ประเภทคลาสหนึ่งFancyMethodมีพารามิเตอร์ประเภทหนึ่งและวัตถุของFancyClassประเภทพารามิเตอร์จะถูกส่งผ่านไปยังวิธีการ

ตามที่คุณเห็นได้ชัดเจนขึ้นในตัวอย่างนี้:

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

ลิงค์จะกลายเป็น:

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

หรือ "ชั้นกับพารามิเตอร์สองชนิดซึ่งมีวิธีการที่มีสามพารามิเตอร์ชนิดพารามิเตอร์ที่วิธีการที่มีClassType1, ClassType2, MethodType1, MethodType2, MethodType3"


ในฐานะที่เป็นบันทึกเพิ่มเติมฉันไม่พบเอกสารนี้ที่ใดก็ได้และฉันไม่ใช่อัจฉริยะผู้แปลบอกฉันทั้งหมดนี้ สิ่งที่คุณต้องทำคือสร้างโครงการทดสอบเปิดใช้งานเอกสาร XMLแล้วใส่รหัสที่คุณต้องการใช้งานลิงค์และวางจุดเริ่มต้นของความคิดเห็นเอกสาร XML ไว้ที่ ( ///):

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

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

จากนั้นสร้างโครงการของคุณและเอกสาร XML ที่แสดงผลมีลิงก์ในองค์ประกอบdoc-> members-> memberภายใต้แอตทริบิวต์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
สิ่งนี้ควรเพิ่ม upvotes มากขึ้นโดยเฉพาะอย่างยิ่งเนื่องจากกลอุบายในการค้นหาสัญกรณ์ที่ถูกต้องโดยไม่ต้องผ่านการลองผิดลองถูก รุ่งโรจน์คนของฉัน
ปีเตอร์

10

เพิ่มเติมจากคำตอบของ Lasse และ TBC:

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

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

จะให้คำแนะนำเครื่องมืออย่างถูกต้องในขณะที่เวอร์ชันของพวกเขาแสดงด้วยเครื่องหมายปีกกา


2
ใช้<ดู 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> - คุณสนใจที่จะอธิบายรายละเอียดเกี่ยวกับวิธีการใช้งานนี้ได้อย่างไร
Jakub Januszkiewicz

2
สวัสดีจาคุบสิ่งนี้ดูเหมือนจะไม่ได้ผลแน่นอน วิธีเดียวที่ฉันจะได้รับคำแนะนำเครื่องมือให้ทำงานอย่างถูกต้องก็คือ <ดู cref = "T: <fullTypeName>` 1 {T} "/>
Stephen Drew

2
ตกลงฉันได้รับบางส่วน หากวิธีการนั้นไม่ได้เป็นแบบทั่วไป (เช่นในรายการ <T> .Add ()) การทำงานนี้: <ดู cref = "M: System.Collections.Generic.List`1 {T}. เพิ่ม (T)" /> .
Jakub Januszkiewicz

1
ดูเหมือนจะไม่ได้ผลสำหรับฉัน ฉันมี<ดู cref = "M: System.Collections.Generic.List`1 {T}" />ในส่วนหัวของข้อคิดเห็นสำหรับวิธีการขยายทั่วไปที่ฉันเขียน (แปลง ArrayList เป็นรายการ <T>) แต่ตั้งค่าสถานะ ReSharper เป็นข้อผิดพลาดทางไวยากรณ์และ IntelliSense เพิ่งแสดงคำต่อคำ VS 2010 / R # 6.1.37.86
Mike Loux

8
Aha! ฉันสามารถรับ<ดู cref = "T: System.Collections.Generic.List`1" /> "ให้ทำงานดังนั้นการใช้ T: แทนที่จะใช้วงเล็บปีกกาเป็นวิธีทำเคล็ดลับมันขยายชื่อเต็มแบบเต็ม และเคล็ดลับการทำงานไม่ได้ถ้าคุณไม่ได้รวม namespace ดังนั้นมันไม่สมบูรณ์ แต่มันจะทำ.
ไมค์ Loux

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

3
โปรดทราบว่าคำตอบอื่น ๆ ครอบคลุมถึงวิธีการอ้างอิงคลาสทั่วไปคำตอบนี้แสดงวิธีอ้างอิงพารามิเตอร์ประเภทด้วยตัวเองซึ่งเกิดขึ้นกับสิ่งที่ฉันต้องการจะทำ
jrh

โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.