كيفية إنشاء أقسام تعليمات برمجية قابلة للطي بنمط rdoc؟

Question

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

وأعتقد أن HTML_DYNAMIC_SECTIONS قد يسمح لي بذلك، ولكن للأسف، يقول سجل التغيير أن هذا الخيار يؤثر فقط على المخططات والرسوم البيانية.

ربما أستطيع أن أفعل ذلك عن طريق تحرير LAYOUT_FILE?

على أي حال، أيها الأشخاص الأذكياء، كيف يمكنني إجبار Doxygen على إنشاء أقسام تعليمات برمجية قابلة للطي؟

Answer 1

لو بما في ذلك مصدر الأساليب، وما إلى ذلك، [...] يجعل من الصعب فحص الصفحة, ، لماذا لا تفعل ذلك فقط وصلة إليه (SOURCE_BROWSER = YES) بدلاً من مشتمل هو - هي (INLINE_SOURCES = YES)؟وهذا من شأنه أن يجعل مسح الصفحات أسهل وأسرع في التحميل، وسيظل المصدر قابلاً للوصول (على حساب تحميل صفحة مصدر أخرى).يعتمد على عدد المرات التي تحتاج فيها فعليًا للوصول إلى المصدر، على ما أعتقد.

يقال أن هناك يكون طريقة لإنشاء أقسام تعليمات برمجية قابلة للطي (سيتعين عليك تعديل المصدر وإعادة ترجمة Doxygen):

• أقسام قابلة للطي في مخرجات HTML الخاصة بـ Doxygen تم وضع علامة مع اثنين متداخلة <div>س مثل ذلك:

    <div class="dynheader"><div class="dynsection">
    [collapsible section]
    </div></div>

• يتم تمييز أقسام التعليمات البرمجية المضمنة على النحو التالي: <div class="fragment"><pre class="fragment">...</pre></div>

• وبالتالي، لجعل أقسام التعليمات البرمجية المضمنة قابلة للطي، عليك القيام بذلك أيضًا

  • يُعدِّل الكود الذي يولد ال <div class="fragment"><pre class="fragment">...</pre></div> لتوليد <div class="dynheader"><div class="dynsection">...</div></div> (وربما ضبط بعض CSS)، أو
  • غير ال جافا سكريبت initDynSections() وظيفة يقوم بمسح المقاطع القابلة للطي وطيها للتعرف عليها <div class="fragment"><pre class="fragment"> كواحد منهم.

التنفيذ (أو الذهاب إلى SOURCE_BROWSER الطريق :)) يتم تركه كتمرين للقارئ.حظ سعيد!

أوه، وإذا نجحت في الحصول على رقعة، فسيكون أمرًا رائعًا أن تتمكن من ذلك سلمها إلى ديمتري حتى يتمكن من تضمينه في إصدار مستقبلي.شكرًا!

Answer 2

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

عندما تم طرح هذا السؤال ربما لم تكن هناك إمكانية لذلك تضمين HTML النقي باستخدام htmlonly ولكن مع وضع ذلك في الاعتبار، يمكن للمرء إنشاء أقسام حاوية قابلة للطي باستخدام وظيفة مسماة toggleVisibility

 function toggleVisibility(linkObj)
 {
   var base = $(linkObj).attr('id');
   var summary = $('#'+base+'-summary');
   var content = $('#'+base+'-content');
   var trigger = $('#'+base+'-trigger');
   var src=$(trigger).attr('src');
   if (content.is(':visible')===true) {
     content.hide();
     summary.show();
     $(linkObj).addClass('closed').removeClass('opened');
     $(trigger).attr('src',src.substring(0,src.length-8)+'closed.png');
   } else {
     content.show();
     summary.hide();
     $(linkObj).removeClass('closed').addClass('opened');
     $(trigger).attr('src',src.substring(0,src.length-10)+'open.png');
   } 
   return false;
 }

والذي يتوفر حاليًا في كل مرة يتم فيها إنشاء الوثائق في ملف يسمى dynsections.js الموجود في جذر الوثائق.

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

1. عنصر dom بمعرف فريد id
2. عنصر dom مغلف آخر بمعرف فريد id-ملخص
3. عنصر dom مغلف آخر بمعرف فريد id-محتوى
4. عنصر dom مغلف آخر بمعرف فريد id-مشغل
5. ال id-يجب أن يحتوي عنصر الزناد على أ src سمة تحتوي على حرف واحد على الأقل
6. ال class سمات الحاويات الرئيسية لا يهم

مع أخذ هذه الشروط في الاعتبار، يمكن إنشاء الكود التالي.

## <a href="javascript:toggleVisibility($('#example-div'))">Fold me</a>
## <div id="example-div">
##   <div id="example-div-summary"></div>
##   <div id="example-div-content">
##     <pre>
##       foo
##       bar
##     </pre>
##   </div>
##   <div id="example-div-trigger" src="-"></div>
## </div>
## @htmlonly <script type="text/javascript">$("#example-div").ready(function() { toggleVisibility($("#example-div")); });</script> @endhtmlonly

يتم استخدام كود Doxygen أعلاه لتوثيق كود bash باستخدام باش دوكسيجين لذلك قد يبدو مختلفًا بعض الشيء عن كود الدوكسيجين النقي.تم بالفعل وصف الجزء الأول الذي يتضمن حاويات div مع ذكر الشروط الملائمة لمصدر الوظيفة toggleVisibility وجعله قابلاً للتنفيذ دون أي أخطاء في ضبط تعليقات الدوكسيجين وفقًا لاحتياجاتنا.

بادئة المعرف الفريدة المستخدمة هنا هي example-div.يوجد في السطر الأول إعداد رابط تشعبي لفتح قسم باستخدام جافا سكريبت مباشرة بالاشتراك مع البعض مسج شفرة.

ما تبقى هو الخطوط الملاحية المنتظمة في النهاية.أنه يحتوي على مسج يجب تشغيل البرنامج النصي لطي الجزء المحدد في البداية.بالنسبة إلى bash-doxygen (وربما لغات أخرى)، يجب أن تكون الكتلة عبارة عن بطانة واحدة بسبب نطاق كتلة البرنامج النصي

عادةً ما يتم إدراج المحتويات بين ‎\htmlonly و\endhtmlonly كما هي.عندما تريد إدراج جزء HTML يحتوي على نطاق حظر مثل جدول أو قائمة يجب أن تظهر خارج <p>..</p>، فقد يؤدي ذلك إلى HTML غير صالح.يمكنك استخدام \htmlonly[block] لجعل doxygen ينهي الفقرة الحالية ويعيد تشغيلها بعد \endhtmlonly.

كما لاحظت في توثيق الدوكسيجين وتعليق أسفل الحل الصحيح المحدد لـ إجابة Stackoverflow على تضمين علامات البرنامج النصي في وثائق Doxygen.

شكرا لقرائتك.آمل أن يساعد هذا بعض الأشخاص الذين يأتون إلى هنا.