نکته: هنگام نوشتن کامنت برای یک پکیج، فارغ از اندازه‌ی آن، به یاد داشته باشید که جمله‌ی اول کامنت در فهرست پکیج‌های godoc نمایش داده می‌شود؛ بنابراین بهتر است این جمله خلاصه‌ای دقیق از هدف و کاربرد پکیج باشد.

مستند کردن باگ‌های شناخته شده

کامنت‌هایی که مستقیماً قبل از هیچ اعلان سطح‌بالایی (top-level declaration) قرار نگرفته باشند، در خروجی godoc نمایش داده نمی‌شوند. البته یک استثنای مهم وجود دارد, کامنت‌های سطح‌بالایی که با عبارت BUG(who) شروع می‌شوند، به‌عنوان باگ‌های شناخته‌شده تشخیص داده شده و در بخش Bugs مستندات پکیج نمایش داده می‌شوند. مقدار who باید نام کاربری فردی باشد که می‌تواند اطلاعات بیشتری درباره‌ی آن مشکل ارائه دهد. برای مثال، نمونه‌ی زیر یک باگ شناخته‌شده در پکیج bytes است: 

مستند کردن کد های منسوخ شده (Deprecated)

گاهی یک فیلد از یک struct، یک تابع، یک نوع داده (type) یا حتی یک پکیج کامل دیگر مورد استفاده نیست یا دیگر ضرورتی ندارد، اما برای حفظ سازگاری با برنامه‌های قدیمی همچنان باید باقی بماند. در چنین مواردی، برای مشخص کردن اینکه یک شناسه (identifier) دیگر نباید استفاده شود، یک پاراگراف با عبارت Deprecated: به مستندات آن اضافه کنید و در ادامه دلیل یا توضیح مربوط به منسوخ شدن آن را بنویسید تا درون مستندات نمایش داده شود.

چندین قانون ساده وجود دارد که با در نظر گرفتن آنها باعث می‌شوید داکیومنتی که godoc تولید میکند دارای ساختار یکپارچه تری باشد:

• خط‌های بعدی متن، ادامه‌ی همان پاراگراف در نظر گرفته می‌شوند؛ بنابراین برای شروع یک پاراگراف جدید باید یک خط خالی قرار دهید.
• متن‌های از پیش قالب‌بندی‌شده (pre-formatted) باید با تورفتگی نسبت به متن اطراف خود نوشته شوند (برای نمونه می‌توانید مستندات فایل doc.go در پکیج gob را مشاهده کنید).
• URLها به‌صورت خودکار به لینک‌های HTML تبدیل می‌شوند و نیازی به هیچ نشانه‌گذاری خاصی ندارند.

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

تمام پکیج‌های Go که در مسیر ‍$GOROOT/src/pkg قرار دارند و همچنین پکیج‌های موجود در محیط‌های کاری GOPATH، از طریق رابط خط فرمان و رابط HTTP مربوط به godoc در دسترس هستند. همچنین می‌توانید با استفاده از فلگ -path مسیرهای دیگری را برای ایندکس شدن مشخص کنید، یا کافی است در پوشه‌ی سورس خود دستور زیر را اجرا کنید:

همچنین در صورتی که نیاز است داکیومنت ها بر روی پورت خاصی قرار بگیرند میتوانیم از فلگ -http استفاده کنیم:

برای جزییات بیشتر میتوانید مستندات godoc را بررسی کنید.

توضیحات مفصل تری در مورد قواعد داکیومنت نویسی در گولنگ وجود داره که می‌توانید با مراجعه به مستندات گولنگ آنها را بررسی کنید.

قسمت قبل: معرفی go fix | گولنگ به زبان ساده