مستند سازی در ارلنگ

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

-module(mydouble).
-export([double/1]).
%This function doubles its input
double(X) -> X * 2.

 

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

%%@author Mahdi Hosseini Moghaddam <[e-mail]>
%%@doc Functions calculating triple 
%%@reference from <a href="http://erlang.blog.ir">کتابارلنگ</a>,
%% 2016
%%@copyright 2016 by Mahdi Hosseini Moghaddam
%%@version 0.1

-module(mytriple).
-export([triple/1]).
-import(mydouble,[double/1]).

%%% This function multiplies a number by 3
triple(X) -> X + double(X).

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

17> edoc:files(["mytriple.erl"], [{dir, "doc"}]).

خروجی در یک پوشه جدید ساخته می‌شود. فایل index.html را با مرورگر خود باز کنید، روی نام تابع mytriple کلیک کنید،تصویری مشابه تصویر زیر خواهید دید:

حتما توجه شما به علامت @ در کامنتها جلب شده است. این علامت در حقیقت توضیحی است به برنامه مستندساز ارلنگ که اطلاعات ذکر شده مربوط به چه قسمتی است. اگر خواستید توضیحی برای تابع خود بنویسید که در مستند نهایی ایجاد شده بیاید کافی است از @doc استفاده کنید. علت خالی بودن توضیح تابع triple در شکل بالا عدم استفاده ما از @doc است. کافیست آن را پس از % اضافه کنیم و دوباره فرمان قبل را اجرا کنیم.

%%@author Mahdi Hosseini Moghaddam <[e-mail]>
%%@doc Functions calculating triple 
%%@reference from <a href="http://erlang.blog.ir">کتاب ارلنگ</a>,
%% 2016
%%@copyright 2016 by Mahdi Hosseini Moghaddam
%%@version 0.1
-module(mytriple).
-export([triple/1]).
-import(mydouble,[double/1]).

%@doc This function multiplies a number by 3
triple(X) -> X + double(X).

تا اینجا مستند ما کامل است اما یک نکته وجود دارد، بدلیل آنکه نوع داده ها در ارلنگ بصورت پویاست به این معنی که شما نیازی ندارید نوع متغیر را در هنگام مقدار دهی مشخص کنید اطلاعات در مورد تابع triple هنوز گنگ است. برنامه‌نویسی که مستند فوق را می‌خواند نخواهد دانست که تابع ما ورودی خود را بصورت عددی می‌گیرد یا انواع دیگر. برای این منظور باید از spec- کد استفاده کرد که خیلی شبیه تعریف مجدد تابع است با این تفاوت که انواع داده‌ای را که انتظار داریم دریافت کنیم را مشخص می‌کنیم. تابع ما عدد حسابی یا اعشاری را دریافت می‌کند و خروجی آن نیز عدد حسابی یا اعشاری خواهد بود. کد زیر تغییر یافته تابع ماست. تولید مستند جدید برمبنای آن برعهده شما باشد.

%%@author Mahdi Hosseini Moghaddam <[e-mail]>
%%@doc Functions calculating triple 
%%@reference from <a href="http://erlang.blog.ir">کتاب ارلنگ</a>,
%% 2016
%%@copyright 2016 by Mahdi Hosseini Moghaddam
%%@version 0.1
-module(mytriple).
-export([triple/1]).
-import(mydouble,[double/1]).

%@doc This function multiplies a number by 3
-spec(triple(number()) -> number()).
triple(X) -> X + double(X).

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

15> edoc:files(["mytriple.erl", mydouble.erl"]).