تولید مستندات جاوا توسط javadoc از روی کد منبع

این کتابخانهء خاص رو میخواستم توی برنامهء اندروید خودم استفاده کنم: https://github.com/koush/AndroidAsync
ولی هرچی گشتم مستنداتش رو پیدا نکردم. فقط چندتا مثال محدود و کلی زده، که برای کار کردن بیشتر باهاش کافی نبود.
آقا ما هرچی گشتیم دیدیم نه انگار واقعا این کتابخانه هیچ مستندات API و اینا ندارم.
حتی توی stackoverflow پرسیدم مستنداتش کجاست، ولی پرسشم رو بعنوان آفتاپیک بستن!
رفتم توی فروم forum.ncis.ir پرسیدم، یه نفر گفت که «چرا داره بین سورسش مشخصه دیگه کامنت هایی /** شروع میشن در مورد متد ها و فیلد ها توضیح میده. کافیه با javadoc مستنداتش رو بسازید.» و «javadoc همراه jdk نصب میشه و از خط فرمان اجرا میشه. و help کاملی هم داره. کافیه سورس برنامه رو بهش بدین بعد مستندات رو به صورت html تولید میکنه.»

خلاصه رفتم دربارۀ javadoc تحقیق کردم و بالاخره تونستم فرمانی که داکیومنت های کل کتابخانه رو تولید میکنه پیدا کنم:
javadoc.exe -d c:\docs -sourcepath c:\AndroidAsync-master\AndroidAsync\src -subpackages com

توضیح اینکه c:\docs فولدری هست که فایلهای HTML تولید شده بعنوان مستندات توسط javadoc، در اون ذخیره میشن.
بقیش هم که باید بقدر کافی واضح باشه میتونید خودتون کد منبع کتابخانهء مورد نظر رو دانلود کرده و این داستان رو بررسی و آزمایش کنید.

خلاصه براحتی با همین یک خط فرمان، کلی داکیومنت برای API این کتابخانه برام تولید شد. تر و تمیز و قشنگ.

گفتم این مطلب رو اینجا بذارم شاید بعدا بدرد دیگران هم خورد، و همینطور خودم اگر خواستم دنبال خط فرمانش بگردم دوباره راحت بهش رجوع کنم.
شخصا تاحالا با اینطور ابزارها کار نکرده بودم نمیدونستم اینقدر راحت و خوب هستن.
البته مستنداتی که اینطور تولید میشن یه مستندات حداقلی هستن و خیلی توضیحات یا مثال و اینها ندارن، اما اگر حرفه ای باشید همین حداقل هم احتمالا میتونه کارتون رو راه بندازه (مثل منکه کارم راه افتاد).

4 دیدگاه در “تولید مستندات جاوا توسط javadoc از روی کد منبع

  1. دقیقا همین مطلب در فصل های اغازی کتاب دیتل امده بود…
    ساخت مستندات با استفاده از javadoc
    ….
    فقط برام سوال پیش امد که ایا شما برای یادگیری یک زبان از این دست کتابها استفاده نمی کنید ؟!

    • نمیدونم منظورتون دقیقا چجور کتابیه، چون تاحالا از این سری کتابهای دیتل که البته اسمش رو زیاد شنیدم نخوندم! ولی در گذشته برای یادگیری زبانهای برنامه نویسی و چیزهای دیگه، معمولا رفرنس رسمی اونا رو کامل میخوندم. البته زمان زیادی هم میبرد، چون حجم رفرنس های رسمی زیاده و خیلی وقتا متن خشک و فنی هم دارن. مثلا رفرنس PHP رو کامل خوندم، رفرنس Qt رو خوندم، رفرنس حتی زبان سی شارپ و فریمورک دات نت رو کامل خوندم، رفرنس MySQL رو خوندم، رفرنس آپاچی رو خوندم، پایتون رو خوندم، …
      یعنی شاید یکی دو سال بیشتر وقتم به مطالعه رفرنس ها گذشت. این کار رو لازم میدیدم. هنوزم فکر میکنم کار درستی بود و باعث ورزیده شدن من شد.
      ولی الان مثلا برای برنامه نویسی اندروید دیگه نرفتم رفرنس جاوا رو بخونم یا حتی برم از منبع مختصرتری یاد بگیرم، و حتی رفرنس اندروید رو هم نخوندم و فقط هرچی نیاز دارم ازش درمیارم و با این حال توی چیزی هم گیر خاصی نمیکنم. حالا علتش چیه، خب میشه گفت من بقدر کافی تاحالا رفرنس خوندم با ساختار زبانهای دیگه آشنا شدم جزییات و کلیات خوبی از تقریبا همه چیز و بیشتر استانداردها و ساختارها و روشها و دیدگاه ها و الگوریتم های استفاده شده میدونم، از زبانهای سطح پایین و همه منظوره بگیر تا زبانهای اسکریپتی مثل PHP و پایتون. بنابراین الان احساس نیاز و ضرورتی که در گذشته نسبت به این کار داشتم ندارم، و خب طبیعی است چون زحمت خودمون رو کشیدیم ریاضت لازم رو قبلا متحمل شدیم. واقعا هم وقتی تازه اولین بار با جاوا روبرو شدم یا برنامه نویسی اندروید، تقریبا هیچیش نبود که برام مشکل خاصی باشه و بیشتر چیزها و ساختارها برام انگار آشنا بود انگار از قبل بلد بودم و حتی فکر میکردم جاوا غول بزرگیه ولی مقداری تعجب کردم از اینکه اینقدر بنظرم روشن تر و ساده تر میامد، بهرحال چیز سختی نبود راحت درک و پیشبینی میکردم هرچیزی چیه چطور باید باشه چطور پیادش کردن چطوری کار میکنه و چرا اونطوریه، چون نمونه ها و الگوهای مختلف، روشهای مختلف، استانداردهای مختلف رو قبلا توی مطالعهء زبانهای متعدد دیگه دیدم درک کردم. اینه مثلا این کتابخانهء خاص که توی پروژهء اندرویدم استفاده کردم و توضیح و مثال کاملی نداشت یا رفرنس اندروید رو تونستم براحتی استفاده کنم.

  2. ممنون از پاسختون.
    قطعا و یقینا مطمئن هستم شما هر پروژه ای که بخواهید انجام میدید اما به نظر بنده تسلط و حتی خوندن سطحی تمام رفرنس اندروید هم لازمه چون گاهی وقتا برخی امکاناتی وجود داره که باعث میشه به جای اینکه کوه رو دور بزنیم از تونلی که وجود داره رد بشیم.

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

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

پاسخ دهید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

*

شما می‌توانید از این دستورات HTML استفاده کنید: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>