haredoc(5) File Formats Manual haredoc(5)

haredoc - قالب پرونده مستندات زبان Hare

مستندات زبان Hare در یک زبان نشانه‌گذاری ساده نوشته می‌شوند. به‌طور پیش‌فرض، haredoc(1) مستندات را بدون هیچ‌گونه قالب‌بندی اضافی و به‌شکل تحت‌اللفظی نمایش می‌دهد. سایر ابزارها ممکن است مستندات Hare را به قالب‌های دیگری تبدیل کنند.

متن را می‌توان به‌طور معمول نوشت و برای رعایت محدودیت ۸۰ ستون، آن را به چند خط تقسیم کرد. برای شروع یک بند (پاراگراف) جدید، یک خط خالی وارد کنید.

ارجاعات به سایر اعلان‌ها و ماژول‌ها را می‌توان در قلاب‌ها (کروشه‌ها) نوشت، مانند: [[os::stdout]]. ارجاعات به ماژول‌ها باید شامل یک :: پایانی در شناسه باشند: [[os::exec::]].

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

نمونه‌های کد را می‌توان با شروع خط با یک نویسه تب (tab)، اختیاری همراه با یک فاصله قبل از آن، به کار برد.

این زبان نشانه‌گذاری از کامنت‌های Hare که پیش از نمادهای خروجی‌گرفته (اکسپورت‌شده) در کد منبع شما قرار دارند، و همچنین از فایلی به نام "README" در پوشه ماژول شما، در صورت وجود، استخراج می‌شود.

فایلی به نام "README" در ریشه پوشه یک ماژول Hare به‌عنوان خلاصه‌ای از کل ماژول به کار می‌رود. این فایل باید با یک خلاصه کوتاه تک‌خطی از ماژول با استفاده از نام ماژول (آخرین بخش در شناسه آن)، یک دونقطه، یک فاصله و یک خلاصه آغاز شود، به‌صورت زیر:

memio: memory-backed I/O functions

در ادامه می‌تواند یک خط خالی و سپس خلاصه‌ای مفصل از ماژول با استفاده از قالب مستندسازی شرح داده شده در بالا قرار گیرد.

// Foos the bars. See also [[foobar]].
//
// If you instead want to bar the foos, use one of the functions in
// [[bar::foo::]].
//
// - First, the bars are obtained.
// - They are then fooed.
// - Finally, the result is returned.
//
//      let x = example();
//      assert(x == 0);
export fn example() int = 0;

انتظار می‌رود ابزارهایی که مستندات را به‌منظور تبدیل به قالبی دیگر تجزیه (parse) می‌کنند، پردازش‌های اضافی انجام دهند تا محتوا از بازنمایی متنی اولیه‌اش جدا شود:

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

بخش hare::parse::doc:: در کتابخانه استاندارد تمامی این پردازش‌ها را برای شما انجام می‌دهد.

تجزیه‌کننده‌ها مجازند (و تشویق می‌شوند) در مواجهه با ورودی‌های نامعتبر، مانند یک [[reference]] بدفرم یا پایان‌نیافته، با خطا متوقف شوند.

haredoc(1)

2026-06-01