كيفية توثيق تطبيق Rails؟

Question

لقد بدأت للتو في توثيق تطبيق القضبان. أعلم أن هذا يتم بالفعل بواسطة RDOC ، لذلك تابعت بعض أدلة RDOC فيما يتعلق ببناء الجملة وما إلى ذلك ، لكنني علقت عندما حاولت وصف سمات النماذج والتحققات والعلاقة بين النماذج ، معظمها لأن هذه الأشياء جزء من ActivereCord. لذلك أتساءل عما إذا كان هناك بعض الدليل أو ممارسة جيدة فيما يتعلق بكيفية توثيق تطبيق Rails أو إذا كان هناك شيء أفتقده؟

أعلم أنه يمكنني وضع كل هذا في وصف الفصل ، لكنني أتساءل عما إذا كانت هناك طريقة مرتبطة ارتباطًا وثيقًا بالإعلان نفسه (has_many ، التحقق من صحة _presence_of ، إلخ) وماذا عن السمات؟

Answer 1

أنا شخصيا أفضل ساحة - http://yardoc.org ، كما يفعل وظيفة أفضل في توثيق IMHO. لا أعرف ما إذا كان هناك معالج محدد للقضبان المتاحة ، لكن من السهل جدًا كتابة واحدة - http://yardoc.org/guides/extending-yard/writing handlers.htmlقد يكون مثال جيد هو معالج السمات - جزء من جوهرة الفناء: LIB/YARD/HANDLORS/Ruby/Attribute_handler.rb

Answer 2

تذكر أن اختباراتك هي جزء من الوثائق (للمطورين) ، خاصة إذا كنت تستخدم الخيار حيث يسهل قراءته السيناريوهات. إذا حافظت على أساليبك قصيرة جدًا وهناك طريقة اختبار تحمل اسمًا وصفيًا على سبيل المثال "يجب تعيين اسم المستخدمين" ، أجد أنني عادة لا أحتاج إلى تعليقات على الطريقة.

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