آموزش داکیومنت سازی با Doxygen

Doxygen یک نرم افزار رایگان GPL2 برای مستند سازی خروجی برنامه نویسی است.

داکسیژن یا Doxygen یک نرم افزار عمومی و مورد پسند جامعه برنامه نویسان برای تهیه داکیومنت از سورس کد برنامه نویسی می باشد. اولین بار برای سورس سی پلاس پلاس تهیه شده ولی زبان های برنامه نویسی دیگر را هم پشتیبانی می کند از جمله این زبان ها به موراد زیر میتوان اشاره کرد.

• ++C
• C
• Objective-C
• C#
• PHP
• Java
• Python
• IDL
• Fortran
• VHDL
• Tcl
•  D توسعه یافته

وبسایت Doxygen را از اینجا میتوانید باز کنید و مطالعه کنید و همچنین از اینجا به سورس Doxygen میتوانید دسترسی داشته باشید و برای خودتان شخصی سازی کنید.

ویژگی های داکسیژن

• میتونه در فرمت HTML و یا Latex از سورس کد ، خروجی درست کنه که برای موارد آنلاین و افلاین میتوانید استفاده کنید.
• همچنین میتواند در فرمت های (RTF (MS-Word ورد مایکروسافت  ، پست اسکریپت ، PDF هایپرلینک دار و HTML فشرده  خروجی تولید کند.
• شما با داکسیژن میتوانید رابطه ساختاری سورس کد ها را استخراج کنید. این مورد برای یافتن مسیر در سورس کد های بزرگ مفید است.
• همچنین با نرم افزار های جانبی میتوانید گراف وراثتی و رابطه بین المان های مختلف برنامه نویسی را بصورت گراف تهیه کنید.
• و آخرین نکته اینکه یک داکیومنت خیلی ساده مانند داکیومنت خود وبسایت Doxygen میتوانید تهیه کنید.

مراحل کار داکیومنت سازی با Doxygen :

مرجله اول

نرم افزار Doxygen را از سایت آن برای سیستم عامل مورد نظر دانلود و نصب میکنیم. پیج زیر را باز کردید کمی برید پایین نوشته binary distribution از اینجا باید دانلود کنید.

لینک دانلود ورژن های مختلف برای سیستم عامل های مختلف

مرحله دوم

یکسری کامنت ها در هنگام نوشتن کد مینویسیم که ویژه داکیومنت کردن هستن.

 

توضیحات کامنت گذاری در Doxygen

برای داکیومنت کردن یک نوشته در صفحه اول داکیومنت به شرح زیر مینویسیم.

/mainpage

برای اضافه کردن قسمت جدید از کامنت زیر استفاده میکنیم:

\section

و برای زیر قسمت از کامنت زیر استفاده میکنیم:

\subsection

اسم فایل

@file

اسم نویسنده

@author

تاریخ

@date

توضیح کوتاه یک فایل یا کد

@brief

برای اضافه کردن کد به توضیحات از کلمات کلیدی زیر استفاده میکنیم

@code

@endcode

برای توضیحات متغییر ها و enum و ماکروها مثل زیرز عمل میکنیم:

Int X /**<default state.*/

برای نوشتن خروجی تابع از کلمه کلیدی  زیر استفاده میکنیم:

@return

برای نمایش Note , warning  در توضیحات میتوانیم از کلمات کلیدی زیر استفاده کنیم که رنگ قرمز و زیر میشه خروجی ها

@note

@warning

البته همه ی این کلمات کلیدی داخل کد بصورت کامنت نوشته می شوند.

نکته مهم در کامنت : دوتا * میذاریم مثال :

/**

*@brief

**/

مثال دیگر با اکثر کلمات کلیدی :

/**

@file main.c

@brief  This is a main file of projects and etc

@date : 97/2/2

@author : Jahandideh

\mainpage Description about file

**/

برای توابع از کامنت  زیر قبل از تعریف تابع میتوانیم استفاده کنیم:

/**

*Function name or Description (Test Function)

*@brief brief of function and main function useage description

*param[in] void

*return void

**/

Void Test_Function(void){

//Statements

}

آموزش داکیومنت سازی با Doxygen برای زبان های C

یک مثال عملی، این کد در محیط Keil به زبان C و برای میکروکنترلر LPC1768 نوشته شده ولی هیچ و هیچ فرقی ندارد و شما برای محیط های مختلف شما از Doxygen میتوانید استفاده کنید.

/**************************************************************************//**
 * @file Doxygen-test.c
 * @brief This Code doesn't do any things it is just for test Doxygen documentation
 * Keil ARM NXP LPC17xx Device
 * @version: V1.09
 * @date: 4. febuary. 2018
 * @author: M.Jahandideh
 * @note
 * This is a Note
 * @warning
 * Warning Test ; this is a Warning
 *
 * \mainpage Description of our Doxygen Test
 * This is a Code to describe our doxygen test
 *
 ******************************************************************************/

/***********
 * Include Files
 * @brife includes
 */
 #include <lpc17xx.h>
 #include <lpc17xx_gpio.h>

/**
 *Test Function
 *@brife Test Function brife
 *@param[in] void
 *@return void
 **/
 void Test_function(void)
 {
 /* This is a Description of Test Functions*/
 }

int main(void){

while(1);

}

آموزش داکیومنت سازی با Doxygen برای آردوینو

یک مثال برای آردوینو

/**************************************************************************//**
 * @file Doxygen-for-arduino.ino
 * @brief This Code doesn't do any things it is just for test Doxygen documentation on Arduino
 * Arduino Dep of Melec.ir
 * @version: V1.0
 * @date: 27. april. 2018
 * @author: M.Jahandideh
 * @note
 * please dont copy and just link to our site
 * @warning
 * Warning Test ; this is a Warning 
 * \mainpage Description of our Doxygen test on Arduino platform
 * This is a Code to describe our doxygen test
 *
 ******************************************************************************/
 
/****************************************************************************
 * Include Files
 * @brife includes
 ******************************************************************************/
#include <SPI.h>

/****************************************************************************
 *@brife sum two inputs a and b 
 *@param[in] int (integer number a and b) 
 *@return int (sum of a and b)
 ******************************************************************************/
 int Test_Function(int a , int b)
 {
 /* This is a Description of Test Functions*/
 return (a+b);
 }


/****************************************************************************
 *@brife Setup Function it is just call once
 *@param[in] void
 *@return void
 ******************************************************************************/
void setup() {
 // put your setup code here, to run once:
 Serial.begin(9600);

}

/****************************************************************************
 *@brife Loop function in Arduino 
 *@param[in] void
 *@return void
 ******************************************************************************/
void loop() {
 // put your main code here, to run repeatedly:
 Serial.println(Test_Function(2,4)); 
}

مرحله سوم 

نرم افزار Doxygen را باز میکنید مراحل را از روی عکس های زیر ادامه دهید تا خروجی HTML تولید شود.

مرحله یک ، این مرحله فقط برای سورس های آردوینو لازم است و برای سورس های نرم افزار های دیگر لازم نیست علتش هم پسوند .ino فایل های آردوینو می باشد که مشکل ساز می‌شوند. پسوند فایل های آردوینو را به cpp تغییر نام می دهیم و مشکل حل میشه 🙂

مرحله دو ، در این مرحله پوشه ای که سورس کد داخل آن قرار دارد را مشخص میکنیم. و همچنین اسم پروژه و پوشه ای که میخواهیم خروجی پروژه در داخل آن قرار گیرد.

مرحله سه ،  زبان برنامه نویسی مورد نظر را انتخاب می کنیم.

مرحله چهار ،  نوع خروجی را انتخاب میکنیم.

مرحله پنج ، همانطور که توضیح دادیم یکی از ویزگی های داکسیژن تولید گراف است و اگر نرم افزار GraphViz  روی سیستم باشد میتواند عکس های گراف تولید کند ولی ما چون نصب نکردیم از حالت خود نرم افزار استفاده می کنیم.

مرحله شش ، نرم افزار را اجرا می کنیم تا داکیومنت ها تولید بشن.

مرحله هفت ، بفرمائید خروجی مستند شده از برنامه نویسی شما ، البته این ورژن خیلی ساده مستند سازی است و برای پروژه های بزرگ خیلی خوشگل تر میتوانیم این کار را انجام دهیم.

اگر این نوشته‌ برایتان مفید بود لطفا کامنت بنویسید.