بلاک مستند یا dockblock چیست
بلاک مستند یا DocBlock یک بلاک کامنت در سورس کد برنامه میباشد که به شکل خاصی فرمت شده تا مستند خلاصه ای از عملکرد تابع و کلاس باشد.
جی اس داک یا JSDoc یک زبان نشانه گذاری برای شرح کلاس ها و توابع جاوا اسکریپتی میباشد.
نکته: در زبان ها مختلف, زبان های نشانه گذاری مختلفی برای مستندات وجود دارد؛ یکی از رایج ترین زبان های نشانه گذاری برای javascript زبان نشانه گذاری JSDoc میباشد.
نکته: ساختار dockblock ها در زبان های مختلف مثل PHP, C و C++ بسیار مشابه, یا یکسان است.
بلاک های مستند به IDE ها کمک میکنند تا توضیحات مناسبی را درباره پارامتر های متد ها و کلاس ها و توابع به برنامه نویس بدهند. این توضیحات معمولا به صورت Popup Parameter Info به کاربر ارائه میشوند.
ساختار dockblock در زبان های خانواده C
پارامتر ها
برای توضیح پارامتر ها ابتدا param را وارد میکنیم سپس نوع data type را بیان میکنیم و سپس نام متغیر یا پارامتر و در انتها توضیحات پارامتر..
/**
*
* Functions Description
*
* @param datatype argument The description of the argument
*
*/آرایه ها
/**
* Method Description
*
* @param array $params description.
* $params = [
* 'key1' => (int) An integer is required.
* 'key2' => (string) A string is required.
* 'key3' => [
* 'key1' => (object) An object is required.
* ]
* ]
*/