واجهة مستخدم مدونة (YUIBlog)

كارلو Zottmann في موضوع دانا ليوي الوثيقة

أود أن أغتنم يوي دوك لجميع احتياجاتي الوثائق جافا سكريبت. لقد وجدت أنه يعمل بشكل جيد لتوثيق شبيبة الفانيليا عادي أو رمز مسج -- انها ليست فقط ل يوي تستند المشاريع.

كنت متشككا في البداية ، وأنا أميل إلى كتابة المزيد من مسج من رمز يوي. وكانت مفاجأة سارة لتجد أن يوي الوثيقة دمجها بسهولة في سير العمل الخاص بي ، ويمكن ان تنتج وثائق مفيدة للمشاريع غير يوي بلدي. بالتأكيد ، لديها بعض التوقعات المتعلقة الخ للمشروع بنية الملف ، ولكن أيا من هذه التوقعات showstoppers بالنسبة لي. من ناحية أخرى ، وهو نظام ضوء وأنا لا يمكن الحصول عليها وتشغيلها في أي وقت من الأوقات.

وجود أداة تحليل قانون بلدي مصدر وبناء التلقائى وثائق الجودة بالنسبة لي شيء عظيم -- ليس فقط ليبحث بسرعة وظيفة المكالمات الخ في وقت لاحق ؛ لي فإنه يضيف قيمة بطريقتين :

أولا ، أنا وثيقة قانون بلدي في اي من الاتجاهين من اجل بلدي -- أنا الارجح ستكون لدينا لاعادة الزيارة في غضون أشهر قليلة ، ويجب ان اكون قادرا على يستلم السلعة بسرعة. عدم وجود وثائق وسائل بعض اللبس في المستقبل ، وهي ليست انطباعا أريد أن أعطي زبائني.

ثانيا ، قد الوثائق رمز يكون قليلا من مفهوما مجردا عن العميل : استطيع ان اقول لها انها هناك ، ولكن الطريقة الوحيدة التي استطيع ان "يثبت" مطالبة بلدي من جراء اطلاق النار محرر بلدي ونقطة إصبعي في كتل تعليق في بلدي رمز. التي حقا لا تبدو مؤثرة جدا -- في أسوأ الأحوال أنها تبدو وكأنها عذر نعتذر عن وثائق "المناسب".

اطلاق النار حتى الآن في المتصفح الخاص بي وعرض التعليقات ذاتها وتحليل الوثيقة التي تتم معالجتها بواسطة يوي -- النظيفة ، وتلألأ ومتماسكة -- والآن التعليمات البرمجية التي المهنية monkeying هناك حق ، والناس.

(إذا كنت مجرد التفكير "رمز موثقة في ويكي غير جيدة وأقل من المتاعب" ، وتفضلوا بقبول حزينة التصفيق الغولف بلدي -- انها ليست. لان)

للأسف ، أنا لست مروحة من الجلد قاعدة الوثيقة يوي. عندما تسليم قطعة موثقة بقوة من رمز لموكلي ، وأريد لهم ان يروا رمز موثقة بقوة ؛ لي ، موضوع الوثيقة يوي الافتراضي لا يكفي تألق الزاهية.

أبحث عن موضوعات حول استبدال لم أستطع أن أجد أي. بضعة أسابيع حتى منذ قررت أن أكتب بلدي -- دانا . ها هي قطة سبيل المثال :

كما ترون أعلاه ، لقد ولدت أنا المعروفة يوي مستندات المعهد كمثال على ذلك. ها هي وثائق أصلية يوي -- وهنا الوثائق ذاتها الرياضية الجديدة موضوع دانا .

أجد أكثر إرضاء الأخير للعين -- وآمل أن توافق! انقر فوق حول قليلا ، والتحقق من بعض الوثائق فئة لأكثر مقارنة متعمقة ، ولعب مع المرشحات ، ويشعر من البلاستيك الفاخر بعد رخيصة تحتها.

وحتى الآن ، لقد حصلت على الكثير من ردود الفعل الإيجابية. زبائني نقدر نظافة نظرة ، وأنا أشعر بشكل أفضل على العرض أكثر مهنية للعمل في مشاريع أضع بلدي ، وصولا إلى توصيف ولدت.

على أي أساس بنيت

لقد بدأت الكتابة دانا عن طريق رمي بعيدا كل بت من داخل أتش تي أم أل الافتراضي يوي الوثيقة القوالب ، بدءا من الصفر وطبقات الخاصة توصيف بلدي على رأس كتل الأساسية ليوي الوثيقة الفهد رمز. (الفهد هو templating محرك بيثون المستخدمة من قبل دوك يوي. و # كتل ستجد في قوالب تحتوي على رمز بيثون التي تنفذها الفهد).

أن نكون صادقين ، ومعرفة ما يدور في القوالب لم يكن حقا نزهة في الحديقة -- يوي الوثيقة في قوالب لا المشروح ، والحصول على المنحى كما وافدا جديدا على النظام استغرق بعض الوقت. التهمت وعندما سنحت لي الشعور فهمت منطق هيكل والفهد ، والباقي من العلامات ، والاستعاضة عنها مع بعض حقا بسيطة يبني ، ومبنية على أعلى من ذلك. استغرق الأمر بعض الوقت.

إذا كنت تعتقد أن الكتابة عن المواضيع الخاصة بك ، كنت توصي باستخدام إما دانة main.tmpl كنقطة انطلاق ، أو يبحث في الاصل منسق بشكل صحيح main.tmpl . توفي العديد من Bothans ليجلب لكم هذا القالب.

أنا لست مصمم ، وأنا حاولت أن تبقي تبدو بسيطة وواضحة دون إضافة الكثير من أجراس وصفارات.

المدمج في الأشياء الجيدة

لقد اتخذت من الحرية لتنفيذ وعرض أفضل (إيمهو) من المعلمات كائن من نوع : إذا كان يتم تمرير المعلمات في عدة خصائص كما على كائن واحد ، الا ان سيتم عرض كائن كمعلمة في أعمدة الجداول الاولى.

فعلى سبيل المثال ، دعونا نقول كنت تتوقع توثيق أسلوب معلمة كائن من نوع التي تحتوي على ثلاث خصائص :

 * @param obj.param1 {String} A string! * @param obj.param2 {Number} A number! * @param obj.param3 {Boolean} A boolean, surprisingly! 

وإليك كيف سيكون عرض هذا الأسلوب في وثائق ولدت :

الافتراضي موضوع : method( obj.param1, obj.param2, obj.param3 )
دانا موضوع : method( obj )

عن الحياة الحقيقية سبيل المثال ، راجع مستندات لل أحداث ق 'YAHOO.widget.DataTable .

أجد أن هذا العلاج يجعل الإخراج أكثر إيجازا.

متطلبات

دانا يتطلب واحدا من الوثيقة يوي يبني في وقت لاحق ، على سبيل المثال ، وبناء 50 يعمل على ما يرام -- لكنها لن تعمل مع الوثيقة يوي 1.0.0b1.

التثبيت / الاستخدام

وأفترض أن كنت قد حصلت على الوثيقة يوي والتي تعمل في هذه النقطة. مجرد تحميل دانا من GitHub ، فك ذلك ، وأخبر yuidoc.py لاستخدامه عن طريق -t/--template الخيار.

ملاحظات ختامية

دانا لا يزال التقدم في العمل ، وهناك بعض القضايا الصغيرة اليسار ، على سبيل المثال مع بعض أتش تي أم أل code القطع التي تخرج واسعة جدا. هذه ليست صفقة قواطع بالنسبة لي ، ولكن الأميال الخاص بك قد تختلف.

بالنسبة لأولئك القراء الذين مثلي ، والحصول على دائخ في دعم فكرة تخفيض السعر في الوثيقة يوي كما أفعل (تلميح ، تلميح) ، وتحقق من الغرب يوي شوكة الوثيقة مايك الذي يضيف بالضبط. بينما ننتظر جديد الأصلي إطلاق الوثيقة يوي ، أعني ؛ * السعال) *

عليك البحث عن دانا GitHub . إذا كنت تميل لذلك كنت ، يمكنك تنزيل أحدث إصدار مستقر باسم / ملف تغز الرمز أيضا. إذا واجهت أي أخطاء ، الرجاء إنشاء تذكرة .

دانا هو مزدوج المرخص لها بموجب الترخيص معهد ماساتشوستس للتكنولوجيا وجنو الإصدار الثاني (v2. وتم اختباره في سفاري 5 (اس اكس) ، FF3.6 (اس اكس) ، IE8 و(ينإكسب).

العثور على المحادثات : المدونات | ستثمبليوبون

وتوسيع نطاق مشاركة : احفظ مع del.icio.us | يسو أنها! | صديق!