แสดงความคิดเห็นการใช้งานในฟังก์ชั่นที่ตั้งใจจะใช้แบบโต้ตอบ

ฉันมีฟังก์ชั่นจำนวนมากที่กำหนดไว้ใน.bashrcเจตนาของฉันที่จะใช้แบบโต้ตอบในเทอร์มินัล ฉันมักจะนำหน้าพวกเขาด้วยความคิดเห็นที่อธิบายการใช้งานที่ตั้งใจ:

# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
  ...
}

นี่เป็นสิ่งที่ดีถ้าเรียกดูซอร์สโค้ด แต่มันก็ดีที่จะรันtypeในเทอร์มินัลเพื่อรับการแจ้งเตือนอย่างรวดเร็วเกี่ยวกับสิ่งที่ฟังก์ชั่นทำ อย่างไรก็ตามสิ่งนี้ (เข้าใจได้) ไม่รวมความคิดเห็น:

$ type foo
foo is a function
foo ()
{
    ...
}

สิ่งใดที่ทำให้ฉันคิดว่า "จะไม่ดีถ้าความคิดเห็นเหล่านี้ยังคงอยู่เพื่อที่typeจะสามารถแสดงได้" และในจิตวิญญาณของงูหลามของdocstringsฉันมาด้วยนี้

foo() {
  : Usage: foo [bar]
  : "Foo's a bar into a baz"
  ...
}

$ type foo
foo is a function
foo ()
{
    : Usage: foo [bar];
    : "Foo's a bar into a baz";
    ...
}

ตอนนี้การใช้งานรวมอยู่ในtypeผลลัพธ์! แน่นอนว่าคุณสามารถดูข้อความได้กลายเป็นปัญหาซึ่งอาจเกิดข้อผิดพลาดได้ง่าย แต่เป็นประสบการณ์การใช้งานที่ดีกว่าเมื่อทำงาน

ดังนั้นคำถามของฉันคือมันเป็นความคิดที่น่ากลัวหรือไม่? มีทางเลือกที่ดีกว่า (เช่นman/ infoสำหรับฟังก์ชั่น) สำหรับการให้ผู้ใช้ฟังก์ชัน Bash พร้อมบริบทเพิ่มเติมหรือไม่?

ฉันยังคงต้องการคำแนะนำการใช้งานที่ตั้งอยู่ใกล้กับคำจำกัดความของฟังก์ชั่นเพื่อให้ผู้ที่ดูซอร์สโค้ดได้รับประโยชน์เช่นกัน แต่หากมีวิธี "เหมาะสม" ในการทำเช่นนี้

แก้ไขสิ่งเหล่านี้เป็นฟังก์ชั่นสไตล์ผู้ช่วยที่ใช้งานง่ายและฉันแค่มองหาบริบทเพิ่มเติมแบบโต้ตอบ แน่นอนว่าสำหรับสคริปต์ที่ซับซ้อนมากขึ้นที่แยกวิเคราะห์การตั้งค่าสถานะฉันจะเพิ่ม--helpตัวเลือก แต่สำหรับสิ่งเหล่านี้มันเป็นภาระค่อนข้างมากในการเพิ่มการตั้งค่าความช่วยเหลือให้กับทุกสิ่ง บางทีนั่นอาจเป็นเพียงค่าใช้จ่ายที่ฉันควรยอมรับ แต่การ:แฮ็คนี้ทำงานได้ดีพอสมควรโดยไม่ต้องทำให้แหล่งที่มายากที่จะอ่านการแก้ไขของเรา

ฉันไม่คิดว่ามีวิธีที่ดีเพียงวิธีเดียวในการทำเช่นนี้

ฟังก์ชั่นสคริปต์และไฟล์ปฏิบัติการอื่น ๆ มีข้อความช่วยเหลือหากผู้ใช้มี-hหรือ--helpเป็นตัวเลือก:

$ foo() {
[[ "$1" =~ (-h|--help) ]] && { cat <<EOF
Usage: foo [bar]
Foo's a bar into a baz
EOF
return;
}
: ...other stuff...
}

ตัวอย่างเช่น:

$ foo -h
Usage: foo [bar]
Foo's a bar into a baz

$ foo --help
Usage: foo [bar]
Foo's a bar into a baz