หนึ่งในฟีเจอร์ใหม่ของXcode 5คือความสามารถในการจัดทำเอกสารโค้ดของคุณเองด้วยไวยากรณ์ความคิดเห็นพิเศษ รูปแบบคล้ายกับ doxygen แต่ดูเหมือนจะรองรับชุดย่อยของคุณลักษณะเหล่านั้นเท่านั้น

สนับสนุนคำสั่งใดและคำสั่งใดไม่
ประเพณีของพวกเขาแตกต่างจาก Doxygen หรือไม่?

นี่คือตัวอย่างของตัวเลือกทั้งหมดที่ฉันพบใน Xcode 5.0.2

ที่ถูกสร้างขึ้นด้วยรหัสนี้:

/** First line text.

 Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!

 @a Italic text @em with @@a or @@em.

 @b Bold text with @@b.

 @p Typewritter font @c with @@p or @@c.

 Backslashes and must be escaped: C:\\foo.

 And so do @@ signs: user@@example.com

 Some more text.
 @brief brief text
 @attention attention text
 @author author text
 @bug bug text
 @copyright copyright text
 @date date text
 @invariant invariant text
 @note note text
 @post post text
 @pre pre text
 @remarks remarks text
 @sa sa text
 @see see text
 @since since text
 @todo todo text
 @version version text
 @warning warning text

 @result result text
 @return return text
 @returns returns text


 @code
// code text
while (someCondition) {
    NSLog(@"Hello");
    doSomething();
}@endcode
 Last line text.

 @param param param text
 @tparam tparam tparam text
 */
- (void)myMethod {}

หมายเหตุ:

• คำสั่งที่จะต้องอยู่ใน/** block */, /*! block */หรือนำหน้าด้วยหรือ/////!
• คำสั่งทำงานกับสไตล์@( headerdoc ) หรือ\คำนำหน้า ( สไตล์doxygen ) (เช่น@bและ\bทั้งสองทำสิ่งเดียวกัน)
• คำสั่งมักจะมาก่อนรายการที่อธิบาย (เช่นถ้าคุณพยายามจัดทำเอกสารคุณสมบัติความคิดเห็นจะต้องมาก่อน@propertyข้อความ) พวกเขาสามารถเข้ามาภายหลังในบรรทัดเดียวกันด้วย/*!< , /**<, ,//!<///<
• คุณสามารถเพิ่มเอกสารลงใน เรียนการทำงานคุณสมบัติและตัวแปร
• @returnsทั้งหมดของคำสั่งเหล่านี้จะปรากฏในข้อความสีเขียวเข้มที่มีความหมายว่าพวกเขาเป็นคำสั่งที่ถูกต้องยกเว้น
• คุณอาจต้องสร้างโครงการของคุณ (หรือรีสตาร์ท Xcode) ก่อนที่การเปลี่ยนแปลงเอกสารของคุณจะปรากฏขึ้น

จะดูเอกสารได้ที่ไหน:

1. ในระหว่างการกรอกรหัสคุณจะเห็นข้อความสั้น ๆ :

สิ่งนี้จะแสดงข้อความสั้น ๆ (โดยไม่มีการจัดรูปแบบ) หากไม่มีข้อความสั้น ๆ มันจะแสดงการเชื่อมโยงของข้อความทั้งหมดถึง @block แรก หากไม่มีอยู่ (เช่นคุณเริ่มต้นด้วย @return) จากนั้นจะเชื่อมข้อความทั้งหมดที่ตัดคำสั่ง @ ทั้งหมด

2. คลิกตัวเลือกชื่อตัวระบุ:

3. ในแผงตรวจสอบวิธีใช้ด่วน

(ดูภาพหน้าจอแรก)

4. ใน Doxygen

เนื่องจากคำสั่งใน Xcode 5 เข้ากันได้กับ Doxygen คุณสามารถดาวน์โหลดและใช้ Doxygen เพื่อสร้างไฟล์เอกสาร

หมายเหตุอื่น ๆ

สำหรับการแนะนำทั่วไปเกี่ยวกับ Doxygen และวิธีการจัดทำเอกสารรหัส Objective-C หน้านี้ดูเหมือนจะเป็นแหล่งข้อมูลที่ดี

คำอธิบายของคำสั่งที่รองรับบางส่วน:

• @brief: จะแทรกข้อความที่ด้านบนของฟิลด์คำอธิบายและเป็นข้อความเดียวที่จะปรากฏระหว่างการเติมโค้ด

ต่อไปนี้ใช้ไม่ได้:

• \n: ไม่ได้ขึ้นบรรทัดใหม่ วิธีหนึ่งในการสร้าง newline คือการทำให้แน่ใจว่าไม่มีสิ่งใดอยู่บนบรรทัดนั้น ไม่เว้นแม้แต่ตัวละครเดียว!
• \example

ไม่รองรับสิ่งต่อไปนี้ (ไม่ปรากฏเป็นสีเขียวเข้ม):

• \ อ้างอิง
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• \ relatedalso
• \ rtfonly
• \ secreflist
• \สั้น
• \ ข้อมูลโค้ด
• \ tableofcontents
• \ vhdlflow
• \ ~
• \"
• .
• ::
• \ |

คำหลักที่สงวนไว้ของ Apple:

Apple ใช้สิ่งที่ดูเหมือนจะเป็นคำหลักที่สงวนไว้ซึ่งใช้งานได้กับเอกสารของพวกเขาเท่านั้น แม้ว่าจะปรากฏเป็นสีเขียวเข้ม แต่ดูเหมือนว่าเราไม่สามารถใช้งานได้เหมือนที่ Apple ทำ คุณสามารถดูตัวอย่างการใช้งานของ Apple ในไฟล์เช่น AVCaptureOutput.h

นี่คือรายการคำหลักบางส่วน:

• @abstract, @availibility, @class, @discussion, @deprecated, @method, @property, @protocol, @related, @ref

ที่ดีที่สุดคำหลักจะทำให้บรรทัดใหม่ในฟิลด์คำอธิบาย (เช่น @discussion) ที่แย่ที่สุดคำหลักและข้อความใด ๆ ที่ตามมาจะไม่ปรากฏในความช่วยเหลือด่วน (เช่น @class)

Swift 2.0ใช้ไวยากรณ์ต่อไปนี้:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

สังเกตว่า@paramตอนนี้เป็นอย่างไร- parameterอย่างไร

ตอนนี้คุณสามารถรวมสัญลักษณ์แสดงหัวข้อย่อยในเอกสารของคุณ:

/**
        - square(5) = 25
        - square(10) = 100
    */

Senseful:

คุณอาจต้องสร้างโครงการของคุณก่อนที่การเปลี่ยนแปลงเอกสารของคุณจะปรากฏขึ้น

บางครั้งมันก็ไม่เพียงพอสำหรับฉัน การปิด Xcode และการเปิดโครงการสำรองมักจะแก้ไขกรณีเหล่านั้น

ฉันยังได้รับผลลัพธ์ที่แตกต่างกันในไฟล์. h และไฟล์. m ฉันไม่สามารถรับบรรทัดใหม่เมื่อความคิดเห็นเอกสารประกอบอยู่ในไฟล์ส่วนหัว

การจัดรูปแบบส่วนใหญ่มีการเปลี่ยนแปลงสำหรับ Swift 2.0 (ตั้งแต่ Xcode 7 ,3 ซึ่งเป็นจริงในß4)

แทน :param: thing description of thing (เหมือนเดิมใน Swift 1.2)

ตอนนี้ - parameter thing: description of thing

ส่วนใหญ่ของคำหลักได้ถูกแทนที่ด้วยแทน- [keyword]: [description] :[keyword]: [description]ขณะนี้รายการของคำหลักที่ไม่ได้ทำงานรวมถึงabstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, ,relatedref