توثيق برمجيات php

[اميرة عبد الدايم]

كنت قد كتبت مقال كامل عن طريقة توثيق البرمجيات بلغة php باستخدام المعايير القياسية في phpDoc < هذا التوثيق الذي يكون خاص بالمطورين (developers documentation)

اقتبس لكم الفقرة الاولى والثالة من المقال :
1 – المقدمة (Introduction) :

الهدف الاساسي من هذه التدوينة هو شرح كامل لمعايير PHPDoc لتكون قادر على انشاء توثيق جيد لبرمجياتك .

كثير من المطورين العرب لا ينشؤون توثيق للمستخدم فما بالك بانشاء توثيق للمطورين ؟

بحثت في المواقع العربية عن شرح واحد لهذا الموضوع وللاسف لم اجد فكان لا بد من كتابة هذا المقال لاهميته .

اذا كنت لا تعرف PHPDoc بكل بساطة يمكنك زيارة الموقع الخاص به PHPDocumentor .

ساتحدث في هذا المقال على افضل الممارسات في كتابة التوثيق والمعيار الصحيح في كتابة توثيقات للمطورين .

3- تعريف بعض المصطلحات (Definitions) :

PHPDoc : هي جزء من التوثيق التي تحتوي على معلومات جوانب من Structural Element
من المهم أن نلاحظ أن PHPDoc وDocBlock كيانين منفصلين

DocBlock هو مزيج من DocComment، وهو نوع من الملاحظات (التعليقات)،

PHPDoc وهو الذي يحتوي على الجمل الوصف لهذه التعليقات (سيتم توضيح هذه النقطة في الجزء الخامس من المقالة)
Structural Element : وهو عبارة عن التعليمات البرمجية التي يجب ان يسبقها DocBlock وهي كما يلي :

file
require(_once)
include(_once)
class
interface
trait
function (including methods)
property
constant
variables, both local and global scope.
مثال :
كود PHP:

/**
* This is the summary for a DocBlock.
*
* This is the description for a DocBlock. This text may contain
* multiple lines and even some _markdown_.
*
* * Markdown style lists function too
* * Just try this out once
*
* The section after the description contains the tags; which provide
* structured meta-data concerning the given element.
*
* @author Mike van Riel <[email protected]>
*
* @since 1.0
*
* @param int $example This is an example function/method parameter description.
* @param string $example2 This is a second example.
*/

لا اود نسخ المقال كاملا لكبر حجمه , فاذا كان الموضوع قد يهمك مكنك القاء نظرة على المقال من هنا : http://goo.gl/Aw25ru