كيف تكتب وثائق الحزمة الخاصة بك؟ [مغلق

Question

لم أحسب تمامًا سير عمل معقول لبناء الحزم وكتابة وثائقها.

أريد أن يتم إنشاء أكبر قدر ممكن من العملية (والوثائق) تلقائيًا.

يبدو أن الطريقة الواضحة للقيام بذلك هي للاستخدام package.skeleton لإنشاء ملفات الحزمة الأساسية ، ثم الكتابة فوق البرمجي DESCRIPTION ملف و Rd الملفات. المشكلة في ذلك هي أنك تفقد الحقول التي تم إنشاؤها تلقائيًا والتي تضمن أنك تذكرت توثيق جميع المعلمات الصحيحة.

أود أن أعرف كيف أنت اذهب حول بناء الحزم وكتابة الوثائق. هل هناك أي أدوات متاحة لجعل العملية أسهل؟ ((Roxygen يبدو أنه تم تصميمه لهذا النوع من الأشياء ؛ هل هناك برنامج تعليمي جيد لذلك؟ وهل هناك بدائل؟)

Answer 1

أستخدم Roxygen لجميع مشاريعي. على سبيل المثال ، تصفح المصدر ل ال Webvis حزمة. يستخدم Hadley أيضًا Roxygen لتوثيقه (على سبيل المثال ، انظر حزمة Lubridate).

على حد علمي ، لم يتم توثيق Roxygen إلى ما وراء ViGett الصفحة الرئيسية Roxygen).

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

ومع ذلك ، فإنه لا يؤدي إلى أتمتة الوثائق بمعنى أن بعض أدوات توثيق توثيق تفعل (على سبيل المثال Javadoc): Roxygen يفسر تعليقات R التي تم تنسيقها بشكل صحيح ، لكنها لا تفسر رمز R بأي شكل من الأشكال.

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

أخيرًا ، أدير حزمي في Eclipse (Statet) ؛ العديد من IDE لديها وجهات نظر "مشروع" تساعد في إدارة بنية الحزمة ، لذلك قد ترغب أيضًا في استخدام محرر أكثر تقدماً.

Answer 2

فيما يتعلق بموارد Roxygen ، ظهر العديد منها منذ ذلك الحين ، وقد ظهر عدد قليل منها ، على حد تعبيره ملاحظاتي الخاصة:

في كثير من الأحيان عندما أكون google roxygen أو roxygen2 ، أواجه مشكلة في العثور على وثائق. إليك مجموعة من بعض الموارد الرئيسية:

• هادلي ويكهام لديه عظيم مقدمة للميزات الأساسية لـ Roxygen 2

• هناك العديد من المقالات القصيرة المدرجة على موقع Cran لـ Roxygen 2

• Rstudio لديه ملاحظات على تشغيل Roxygen

• رمز مصدر حزمة Roxygen2 على Github