ฉันจะหลีกเลี่ยงอักขระในความคิดเห็น c # ได้อย่างไร

112

วันนี้ฉันตระหนักว่าฉันไม่รู้ว่าจะหลีกหนีตัวละครในความคิดเห็นสำหรับ C # อย่างไร ฉันต้องการจัดทำเอกสารคลาส C # ทั่วไป แต่ฉันไม่สามารถเขียนตัวอย่างที่ถูกต้องได้เนื่องจากฉันไม่รู้วิธีหลีกเลี่ยง<และ>อักขระ ฉันต้องใช้<และ>? ฉันไม่ชอบถ้าเป็นเช่นนั้นเพราะฉันต้องการทำให้ง่ายต่อการอ่านความคิดเห็นในเอกสารจริงดังนั้นฉันจึงไม่ต้องสร้างเอกสารรหัสบางประเภทเพื่อให้สามารถอ่านโค้ดตัวอย่างได้

c#

— Tomas Jansson
แหล่งที่มา

1

คุณช่วยแสดงความคิดเห็นตัวอย่างได้ไหม

— BoltClock

สามารถทำซ้ำสตริง Xml ในความคิดเห็นสรุป C #

— ทำเครื่องหมายพิม

1

@Mark: คุณพูดถูก แต่ไม่ใช่แค่ XML เท่านั้น ... ฉันพยายามเขียนตัวอย่างสำหรับ generics ซึ่งไม่ใช่ XML แต่ใช้ '<' และ '>' แต่วิธีแก้ปัญหาจะเหมือนกันสำหรับทั้งสองอย่าง

— Tomas Jansson

ด้วยความนิยมของเทมเพลตใน C ++, Java, C # ... Microsoft มีข้อแก้ตัวอะไรที่เป็นไปได้สำหรับการใช้ตัวคั่น XML แบบครึ่งหน้า การขาดความชัดเจนและการมองการณ์ไกลตามปกติ

— Rick O'Shea

141

หากคุณต้องการหลีกเลี่ยงอักขระในความคิดเห็น XML คุณต้องใช้เอนทิตีอักขระดังนั้น<จะต้องใช้ Escape เป็น<เดียวกับในคำถามของคุณ

ทางเลือกอื่นในการหลบหนีคือการใช้ CDATAส่วนต่างๆเพื่อให้ได้ผลเช่นเดียวกัน

ตามที่คุณสังเกตสิ่งนี้จะสร้างเอกสารที่ดูดี แต่มีความคิดเห็นที่น่ากลัวในการอ่าน ...

— Oded
แหล่งที่มา

19

เพียงสำหรับการอ้างอิง<จะเป็น<และจะเป็น> >ดังตัวอย่างList<string> myStringList = new List<string>();

— Arvo Bowen

@ArvoBowen ในกรณีที่มีบางคนหายไปอย่างชัดเจนlt/ gtยืนสำหรับ "น้อยกว่า" / "มากกว่า" ตามลำดับ

— Lukas Juhrich

1

น่าสนใจเพียง แต่<ต้องได้รับการหนีด้วย<, สามารถเข้าพักขณะที่มันเป็น:> List<string> myStringList = new List<string>();อย่างน้อยก็ใช้งานได้ใน Intellisense แปลกพอCDATA ไม่ทำงานใน Intellisense ฉันไม่ได้ตรวจสอบว่าหน้าตาเป็นอย่างไรในเอกสารที่สร้างขึ้นอัตโนมัติ

— Peter Huber

สามารถยืนยันได้ว่า VS 2013 ไม่แสดงผลCDATAใน Intellisense <ทำให้ความคิดเห็นอ่านยาก

— Alex

52

ในความคิดเห็น C # ธรรมดาคุณสามารถใช้อักขระใดก็ได้ (ยกเว้น*/ว่าคุณเริ่มต้นความคิดเห็นด้วย/*หรือขึ้นบรรทัดใหม่หากคุณเริ่มต้นความคิดเห็นด้วย//) หากคุณกำลังใช้ความคิดเห็น XML คุณสามารถใช้ส่วน CDATAเพื่อรวมอักขระ '<' และ '>'

ดูบทความบล็อก MSDNสำหรับข้อมูลเพิ่มเติมเกี่ยวกับความคิดเห็น XML ใน C #

ตัวอย่างเช่น

/// <summary>
/// Here is how to use the class: <![CDATA[ <test>Data</test> ]]>
/// </summary>

— มาร์คพิม
แหล่งที่มา

12

คุณอาจจะถูกต้องถ้าคุณต้องการสร้างเอกสาร html ที่ดูดี แต่ฉันน่าสนใจกว่าเกี่ยวกับการรับเคล็ดลับ Intellisense ใน VS ที่ถูกต้องและดูเหมือนว่าฉันต้องใช้ XML Escape แต่ +1 สำหรับทางเลือก

— Tomas Jansson

2

อืมขยะเครื่องที่อ่านไม่ออกในความคิดเห็นของฉันจะช่วยได้ก็ต่อเมื่อเราใช้เวลาในการสร้างไฟล์เอกสารของเราเมื่อกรณีการใช้งานส่วนใหญ่กว้างใหญ่ไพศาล (ฉันพูดถึงกว้างใหญ่หรือไม่) กำลังอ่านความคิดเห็นในแหล่งที่มา (ควรเป็นอินเทอร์เฟซ) .

— Rick O'Shea

19

คุณบอกว่า "ฉันต้องการให้ง่ายต่อการอ่านความคิดเห็นในเอกสารฉบับจริง" ฉันเห็นด้วย.

นักพัฒนาใช้ชีวิตส่วนใหญ่ในโค้ดโดยไม่ได้อ่านเอกสารที่สร้างขึ้นโดยอัตโนมัติ สิ่งเหล่านี้ยอดเยี่ยมสำหรับไลบรารีของบุคคลที่สามเช่นการสร้างแผนภูมิ แต่ไม่ใช่สำหรับการพัฒนาภายในองค์กรที่เราทำงานร่วมกับโค้ดทั้งหมด ฉันตกใจมากที่ MSFT ไม่ได้คิดค้นโซลูชันที่รองรับนักพัฒนาได้ดีกว่าที่นี่ เรามีพื้นที่ที่ขยาย / ยุบโค้ดแบบไดนามิก ... ทำไมเราไม่สามารถสลับการแสดงความคิดเห็นแทน (ระหว่างข้อความดิบและความคิดเห็น XML ที่ประมวลผลหรือระหว่างข้อความดิบและความคิดเห็น HTML ที่ประมวลผลแล้ว) ดูเหมือนว่าฉันควรมีความสามารถ HTML เบื้องต้นในความคิดเห็นเกี่ยวกับวิธีการ / คลาสของฉัน (ข้อความสีแดงตัวเอียง ฯลฯ ) แน่นอนว่า IDE สามารถใช้เวทมนตร์ในการประมวลผล HTML เล็กน้อยเพื่อทำให้ความคิดเห็นแบบอินไลน์มีชีวิตชีวา

วิธีแก้ปัญหาการแฮ็กของฉัน: ฉันเปลี่ยน '<' เป็น "{" and '> "เป็น"} "ซึ่งดูเหมือนจะครอบคลุมฉันสำหรับความคิดเห็นเกี่ยวกับสไตล์การใช้งานตัวอย่างทั่วไปรวมถึงตัวอย่างเฉพาะของคุณด้วยไม่สมบูรณ์ แต่ใช้งานได้จริง เนื่องจากปัญหาความสามารถในการอ่าน (และปัญหาเกี่ยวกับการระบายสีความคิดเห็น IDE ที่เกิดขึ้นเมื่อใช้ '<')

— เดฟ
แหล่งที่มา

5

"การแฮ็กโซลูชัน" ของคุณดูเหมือนจะถูกต้องมากกว่าที่คุณคิด ตามนี้คอมไพเลอร์จำแนกวงเล็บปีกกาเป็นวงเล็บมุมและผูกให้ถูกต้อง

— RubberDuck

8

ความคิดเห็น C # XML เขียนใน XML ดังนั้นคุณจะใช้การหลีกเลี่ยง XML ปกติ

ตัวอย่างเช่น...

<summary>Here is an escaped &lt;token&gt;</summary>

— บ๊อบแบล็ค
แหล่งที่มา

5

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

เรียบง่าย แต่มีประสิทธิภาพ

— โฮลี่ซาโมซ่า
แหล่งที่มา

0

ดีกว่าการใช้ {... } คือใช้≤ ... ≥ (เครื่องหมายน้อยกว่าหรือเท่ากับเครื่องหมายมากกว่าหรือเท่ากับ U2264 และ U2265 ใน Unicode) ดูเหมือนวงเล็บเหลี่ยมที่ขีดเส้นใต้ แต่ยังคงเป็นวงเล็บเหลี่ยมแน่นอน! และเพิ่มเพียงสองสามไบต์ในไฟล์โค้ดของคุณ

— มิกบรูโน
แหล่งที่มา

0

ลอง U2280 และ U2281 ได้ดียิ่งขึ้น - เพียงคัดลอกและวางจากรายการอักขระ Unicode (ส่วนตัวดำเนินการทางคณิตศาสตร์)

— Paul Coulson
แหล่งที่มา

ตัวดำเนินการ Unicode นั้นใช้ได้เมื่อใช้แทนตัวดำเนินการทางคณิตศาสตร์จริงไม่ดีหากใช้ในข้อมูลโค้ดที่เกิดขึ้นในความคิดเห็น (เช่นList<int>) ลองนึกถึงเช่นการคัดลอกวางข้อมูลโค้ด

— Palec

คุณสามารถให้ตัวอย่างการใช้สิ่งนี้ในความคิดเห็นได้หรือไม่? ไม่เคยใช้อักขระ Unicode อย่างแน่นอน

— ClementWalter

1

คัดลอกและวางอักขระตามที่อธิบายไว้ข้างต้น

— Paul Coulson