طرح‌چه

جدیدترین ها

پربازدیدترین ها

  • X
    ###
    ###
    ###
  • X
    ###
    ###
    ###
  • X
    ###
    ###
    ###
تماس با مااوپن سورس
طرح‌چه | طرحی نو در اندازیم

دیدگاه ها

هنوز دیدگاهی برای این مقاله ثبت نشده!
نیازمند احراز هویت
برای اینکه بتوانید دیدگاه خود را ثبت کنید باید ابتدا وارد حسابتان شوید

نوشتن مستندات و استفاده از Godoc | گولنگ به زبان ساده

user avatar

Mahdi.Kh

۲۷ تیر ۱۴۰۵

نوشتن مستندات و استفاده از Godoc | گولنگ به زبان ساده
با نحوه نوشتن داکیومنت و انتشار اون اشنا میشیم و همچنین یاد میگیریم چطور از Godoc استفاده کنیم.

1

معرفی | گولنگ به زبان ساده

2

آماده سازی محیط توسعه | گولنگ به زبان ساده

3

ساختار برنامه های گولنگی | گولنگ به زبان ساده

4

متغیرها | گولنگ به زبان ساده

5

ثابت ها (constants) | گولنگ به زبان ساده

6

اعداد | گولنگ به زبان ساده

7

بولین (bool) | گولنگ به زبان ساده

8

نوع داده متنی (string) | گولنگ به زبان ساده

9

نوع داده slice | گولنگ به زبان ساده

10

حلقه ها | گولنگ به زبان ساده

11

نوع داده map | گولنگ به زبان ساده

12

تابع (function) | گولنگ به زبان ساده

13

نوع داده struct | گولنگ به زبان ساده

14

اینترفیس (interface) |‌ گولنگ به زبان ساده

15

جنریک ها (generics) | گولنگ به زبان ساده

16

Defer , Panic و Recover | گولنگ به زبان ساده

17

جی‌سان (JSON) | گولنگ به زبان ساده

18

تبدیل داده ها به باینری با استفاده از Gob | گولنگ به زبان ساده

19

معرفی پکیج استاندارد RPC | گولنگ به زبان ساده

20

کنترل خطاها (error) | گولنگ به زبان ساده

21

پکیج و ماژول | گولنگ به زبان ساده

22

reflection | گولنگ به زبان ساده

23

جنریت کردن کد (go generate) | گولنگ به زبان ساده

24

گوروتین ها | گولنگ به زبان ساده

25

چنل‌ها (channels) | گولنگ به زبان ساده

26

کانتکست (context) | گولنگ به زبان ساده

27

یونیت تست (unit test) | گولنگ به زبان ساده

28

استاندارد پکیج time | گولنگ به زبان ساده

29

بررسی استاندارد پکیج sync | گولنگ به زبان ساده

30

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

31

نوشتن مستندات و استفاده از Godoc | گولنگ به زبان ساده

یک بخش از برنامه نویسی, نوشتن مستندات برای کدها است. نوشتن مستندات باعث افزایش توسعه پذیری و دسترسی پذیری نرم افزار میشوند.

گولنگ ابزاری به نام Godoc دارد که کدها را بررسی (scan) میکند و مستنداتی که درون کد فراهم شده است را به صورت صفحات وب در دسترس ما قرار می‌دهد.

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

به‌طور کلی، برای مستندسازی یک نوع داده، متغیر، ثابت، تابع یا حتی یک پکیج (package)، کافی است یک کامنت معمولی را دقیقاً قبل از اعلان کردن (declaration) آن بنویسید؛ به‌طوری‌که هیچ خط خالی‌ای بین کامنت و اعلان وجود نداشته باشد تا godoc این کامنت را به‌عنوان مستندات مربوط به همان مورد نمایش دهد.

به عنوان مثال درون پکیج fmt یک تابع با نام Fprintln وجود دارد که دارای کامنتی همانند زیر است:

// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {

این کامنت‌ها در نهایت در مستندات پکیج منتشر می‌شوند.

هرکدام از این کامنت‌ها یک جمله‌ی کامل است و با نام همان عنصری که توضیح می‌دهد آغاز می‌شود. رعایت این قرارداد مهم باعث می‌شود بتوان مستندات را در قالب‌های مختلفی تولید کرد؛ از متن ساده گرفته تا HTML و حتی صفحات راهنمای UNIX (man pages). علاوه بر این، وقتی ابزارها برای خلاصه‌سازی، بخشی از مستندات را نمایش می‌دهند (برای مثال فقط خط اول یا جمله‌ی ابتدایی را استخراج می‌کنند)، خروجی همچنان خوانا و قابل‌فهم باقی می‌ماند.

کامنت‌هایی که برای اعلان یک پکیج (package) نوشته می‌شوند، باید توضیحی کلی درباره‌ی هدف، کاربرد و محتوای آن پکیج ارائه کنند. به عنوان مثال پکیج sort درون مستندات خود دارای کامنتی مانند زیر است:

// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort

اگر مستندات پکیج شما خیلی مفصل است, میتوانید یک فایل doc.go درون پکیج خود ایجاد کنید و مستندات خود را درون این فایل قرار دهید. معمولا این فایل تنها شامل مستندات است و هیچ کد گولنگی درون آن نوشته نمی‌شوند. به عنوان مثال پکیج gob دارای فایل doc.go است. کامنت هایی که درون فایل doc.go قرار گرفته اند درون مستندات پکیج نیز منتشر میشوند. برای مثال مستندات پکیج gob شامل همان کامنت هایی که در doc.go نوشته شده اند است.

#go#golang#گولنگ

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

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

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

// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.

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

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

 

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

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

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

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

godoc .

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

godoc -http=":6060" .

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

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

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