کد جاوا خود را به صورت خودکار با Javadoc مستند کنید

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

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

جاوا به راحتی یک راه حل داخلی برای مشکل ارائه می دهد: Javadoc.

Javadoc می تواند به شما کمک کند تا کد خود را به طور خودکار مستند کنید

امیدواریم قبلاً از شیوه های کدنویسی خوب پیروی کرده باشید و نظرات توضیحی را در کد خود لحاظ کنید. در حالی که این نوع اظهار نظر درون کد مطمئنا مفید است، اما واقعاً چیزی قابل مقایسه با یک کتابچه راهنمای کاربر ارائه نمی دهد.

مطمئناً، برنامه‌نویس دیگری می‌تواند کد شما را بررسی کند و در مورد کلاس‌ها، متدها و توابع خاصی که در مقابل او قرار دارند مطالعه کند. با این حال، به دست آوردن یک نمای کلی خوب از همه کدها یا یافتن توابعی که زمانی که از وجود آنها اطلاعی ندارید، بسیار دشوار است. هدف Javadoc حل این مشکل است.

Javadoc یک کتابچه راهنمای HTML دقیق و خواننده پسند برای تمام کدهای شما به طور خودکار ایجاد می کند. بهتر از همه، این کار را با استفاده از نظرات کدی که احتمالاً قبلاً نوشته‌اید انجام می‌دهد.

Javadoc دقیقا چیست و چگونه کار می کند؟

Javadoc یک برنامه مستقل است که همراه با کیت توسعه جاوا (JDK) Oracle ارائه می شود. در واقع، شما نمی توانید آن را جداگانه دانلود کنید. هنگامی که یکی از نسخه‌های JDK اوراکل را دانلود و نصب می‌کنید، Javadoc نیز نصب می‌شود.

هنگامی که آن را اجرا می کنید، Javadoc مستندات HTML را از نظرات فرمت شده خاص در کد منبع جاوا شما تولید می کند. این فرآیند اسناد مفیدتر و قابل خواندن را ایجاد می کند و در عین حال بهترین شیوه ها را تشویق می کند.

به طور خلاصه، Javadoc این امکان را برای شما فراهم می کند که کد خود و مستندات آن را همزمان بنویسید. این روند کار شما را ساده می کند و به شما امکان می دهد از زمان خود به نحو احسن استفاده کنید.

نحوه ایجاد نظرات سازگار با Javadoc

Javadoc با تجزیه نظرات با فرمت خاص در کد شما و تبدیل آنها به خروجی HTML کار می کند. تنها تغییری که واقعاً باید انجام دهید این است که رشته های خاصی را در نظرات خود بگنجانید. اینها به Javadoc اجازه می دهد تا بداند چه چیزی را می خواهید در مستندات نهایی قرار دهید.

نظرات Javadoc باید بلافاصله قبل از اعلان کلاس، فیلد، سازنده یا متد باشد. خود نظر باید:

• با سه کاراکتر /** شروع کنید.
• در ابتدای هر خط جدید یک ستاره قرار دهید.
• با دو کاراکتر */ ببندید.

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

در اینجا یک مثال برای نشان دادن نظرات ساده Javadoc وجود دارد که عملکردی را توصیف می کند که یک تصویر را از URL دریافت می کند و آن را روی صفحه چاپ می کند. نظر بلافاصله قبل از عملکرد قرار می گیرد و آنچه را که انجام می دهد توصیف می کند. این بلوک نظرات همچنین از سه تگ مخصوص بخش استفاده می کند: @param، @return و @see.

/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
    try {
        return getImage(new URL(url, name));
    } catch (MalformedURLException e) {
        return null;
    }
}

هنگامی که Javadoc کد بالا را پردازش می کند، یک صفحه وب شبیه به زیر ایجاد می کند:

یک مرورگر خروجی Javadoc را تقریباً به همان روشی که هر سند HTML را نمایش می دهد، رندر می کند. Javadoc فضای سفید اضافی و خط شکن ها را نادیده می گیرد مگر اینکه از تگ های HTML برای ایجاد آن فضا استفاده کنید.

از برچسب های Javadoc برای جزئیات و مراجع خاص استفاده کنید

تگ‌های @ که در انتهای نظر استفاده می‌شوند، بخش‌های Parameters، Returns و See Also را ایجاد می‌کنند که می‌بینید.

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

تگ @return مقداری را که تابع برمی‌گرداند، در صورت وجود، مستند می‌کند. بسته به شرایط می تواند یک توصیف ساده یک کلمه ای یا جملات متعدد باشد.

تگ @see به شما این امکان را می دهد که سایر توابع مرتبط یا مرتبط را تگ کنید. در این حالت، تگ @see به تابع دیگری به نام Image ساده اشاره دارد. توجه داشته باشید که ارجاعات ساخته شده با این تگ پیوندهای قابل کلیک هستند و به خواننده اجازه می دهند به آیتم ارجاع شده در HTML نهایی پرش کنند.

برچسب‌های بیشتری مانند @version، @author، @exception و دیگران در دسترس هستند. وقتی از برچسب ها به درستی استفاده می شود، به ارتباط موارد با یکدیگر کمک می کند و امکان پیمایش آسان در اسناد را فراهم می کند.

اجرای Javadoc بر روی کد منبع شما

شما Javadoc را در خط فرمان فراخوانی می کنید. می‌توانید آن را روی فایل‌های منفرد، کل دایرکتوری‌ها، بسته‌های جاوا یا در فهرستی از فایل‌های جداگانه اجرا کنید. به‌طور پیش‌فرض، Javadoc فایل‌های مستندات HTML را در فهرستی که دستور را وارد می‌کنید تولید می‌کند. برای دریافت راهنمایی در مورد دستورات خاص موجود، به سادگی وارد کنید:

javadoc --help

برای اینکه ببینید Javadoc دقیقاً چه کاری می تواند انجام دهد، به اسناد رسمی Oracle مراجعه کنید. برای ایجاد مجموعه ای سریع از اسناد روی یک فایل یا دایرکتوری، می توانید جاوادوک را در خط فرمان وارد کنید و سپس یک نام فایل یا علامت عام را وارد کنید.

javadoc ~/code/filename.java

javadoc ~/code/*.java

در بالا لیستی از فایل ها و دایرکتوری هایی که Javadoc ایجاد کرده است وجود دارد. همانطور که می بینید، تعداد کمی از آنها وجود دارد. به همین دلیل، هنگام اجرای برنامه باید مطمئن باشید که در همان دایرکتوری کد منبع خود قرار ندارید. انجام این کار می تواند یک آشفتگی ایجاد کند.

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

این مستندات یک کلاس جاوا کوتاه و منفرد برای نمایش خروجی است. هدر نام کلاس و همچنین متدهای موجود در آن را نشان می دهد. پیمایش به پایین تعاریف دقیق تری از هر یک از متدهای کلاس را نشان می دهد.

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

هرگز از طریق نظرات کد به شکار نروید

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

منبع مقاله