آموزش برنامه نویسی

توضیحات و مستند سازی

دوشنبه, ۷ مرداد ۱۳۹۲، ۰۵:۳۳ ب.ظ

کامنت گذاری در جاوا را می توان به دو روش انجام داد. اولین نوع که به سبک زبان C است و توسط ++C نیز به ارث برده شده است. این نوع کامنت گذاری با */ شروع می شود و می تواند چندین خط ادامه داشته باشد و سرانجام با /* خاتمه پیدا می کند. تعداد زیادی از برنامه نویسان برای زیبایی بیشتر، هر خط توضیح را با * شروع می کنند. مثال زیر نمونه ای از این نوع کامنت گذاری است.

/* This is a comment

 

 

 * that continues

 

 

 * across lines

/* 

 

تمام خطوطی که بین */ و /* قرار می گیرند، نادیده گرفته می شوند پس هیچ تفاوتی نمی کند اگر به شکل زیر کامنت را بنویسیم.

 

/* This is a comment that

 

 

 

continues across lines */

 

 

 

نوع دوم کامنت گذاری از ++C گرفته شده است. کامنت گذاری یک خطی که با // شروع می شود و تا پایان همان خط ادامه دارد. این نوع کامنت گذاری به دلیل راحتی، بیشترین استفاده را دارد. مثال زیر نمونه ای از این نوع کامنت گذاری است...

 

This is a one-line comment //

 

کامنت مستند سازی

شاید بزرگترین مسئله ای که در مورد مستند سازی کد وجود دارد نگه داری و مراقبت از مستندات می باشد. اگر مستندات و کد جدای از هم باشند، تغییر مستندات با هر بار تغییر کد کاری ملالت آور و خسته کنده می شود. راه حل ساده ارتباط مستندات و کد با یکدیگر می باشد. ساده ترین راه برای انجام این کار قرار دادن همه چیز در یک فایل می باشد. اما برای این کار نیاز به یک گرامر خاص کامنت گذاری برای علامت گذاری کردن مستندات و ابزاری برای استخراج این کامنت ها و قرار دان آنها در یک شکل مناسب و مفید است. جاوا این کار را برای شما انجام می دهد. ابزاری که جاوا برای استخراج کامنت ها دارد Javadoc نامیده می شود. برای این کار به دنبال تگ های خاص کامنت که شما در برنامه خود قرار داده اید می گردد. خروجی Javadoc یک فایل HTML است که می توانید با مرورگر وب آن را مشاهده کنید. در واقع Javadoc یک فایل سورس کد با پسوند "Java." و یا نام Package را به عنوان ورودی دریافت و یک سند حاوی جزییات را با فرمت HTML تولید می کند. برای تولید یک مستند سازی کامل باید از نوع خاصی از دستورات کامنت گذاری در سورس کد برنامه استفاده کرد. جاوا همچنین یک نوع از کامنت گذاری را دارد که توسط ابزار Javadoc قابل خواندن است. این کامنت گذاری برای شرح المانهایی مثل کلاس ها، متغیرها، اشیاء و متدها مورد استفاده قرار می گیرد. مثال زیر نمونه ای از این نوع کامنت گذاری است که با ...**/ شروع و با /* به پایان می رسد. Javadoc فقط کامنت های مربوط به اعضا public و protected را پردازش می کند. کامنت های مربوط به اعضای private و package-access را نادیده می گیرد. اما شما می توانید از پرچم private- برای اعضای private استفاده کنید. چون خروجی به صورت HTML است از دستورات HTML نیز می توانید استفاده کنید.

 

/** A descriptive sentence or paragraph.

 

 

  * @tag1 Description of this tag.

 

 

  * @tag2 Description of this tag.

 

 

  /*  

 

کامنت مستند سازی باید در بالای المان مورد نظر برنامه قرار بگیرد و مختصر توضیحی راجع به آن ارائه دهد. برای مثال اگر کامنت قبل از دستور کلاس قرار دارد، اهداف کلاس را شرح خواهد داد. علاوه بر متن های توضیحی، گزینه های دیگری نیز وجود دارد که به آنها تگ گفته می شود و می توان برای مستند سازی از آن ها استفاده کرد. این تگ ها همراه با علامت @ استفاده می شوند و با یک فاصله و یک متن یا پاراگراف توضیحی همراه هستند.

 

 

 

نمونه هایی از این تگ ها عبارتند از :

 

see@

 

برای مشخص کردن پیوند به موضوعی دیگر مورد استفاده قرار می گیرد.

 

 

--------------------

param@

 

برای توضیح پارامترهای یک متد مورد استفاده قرار می گیرد.

 

 

--------------------

author@

 

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

 

 

--------------------

version@

 

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

 

 

--------------------

return@

 

برای توضیح مقدار برگشتی یک متد مورد استفاده قرار می گیرد.

 

 

--------------------

و ....

 

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

 

 

abc.java : سورس کد برنامه شما

 

 

\C:\JavaDocs : مسیر پوشه ای که قرار است مستندات در آن ایجاد شوند

 

javadoc -author -version -d C:\JavaDocs\ abc.java

  • امین بهرامی

نظرات (۱)

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

ajavadoc -author -version -d C:\JavaDocs\ abc.jav



این رو در کجا بنویسیم؟؟
پاسخ:
توی cmd این دستور را می نویسیم. البته قبلش باید پوشه bin که در محل نصب jdk  است را به path ویندوز داده باشی.
ارسال نظر آزاد است، اما اگر قبلا در بیان ثبت نام کرده اید می توانید ابتدا وارد شوید.
شما میتوانید از این تگهای html استفاده کنید:
<b> یا <strong>، <em> یا <i>، <u>، <strike> یا <s>، <sup>، <sub>، <blockquote>، <code>، <pre>، <hr>، <br>، <p>، <a href="" title="">، <span style="">، <div align="">
تجدید کد امنیتی