Hiển thị các bình luận sử dụng trong các chức năng dự định sẽ được sử dụng tương tác

Tôi có một số hàm được định nghĩa trong tôi .bashrc, có ý định sử dụng tương tác trong một thiết bị đầu cuối. Tôi thường đi trước họ với một bình luận mô tả mục đích sử dụng của nó:

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

Điều này tốt nếu duyệt mã nguồn, nhưng thật tuyệt khi chạy typetrong thiết bị đầu cuối để nhận được lời nhắc nhanh về chức năng này. Tuy nhiên, điều này (có thể hiểu được) không bao gồm các bình luận:

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

Điều đó khiến tôi suy nghĩ "sẽ không hay nếu những bình luận kiểu này vẫn tồn tại để typecó thể hiển thị chúng?" Và trong tinh thần của Python của docstrings tôi đến với điều này:

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";
    ...
}

Bây giờ việc sử dụng được bao gồm ngay trong typeđầu ra! Tất nhiên như bạn có thể thấy trích dẫn trở thành một vấn đề có thể dễ bị lỗi, nhưng đó là trải nghiệm người dùng đẹp hơn khi nó hoạt động.

Vì vậy, câu hỏi của tôi là, đây có phải là một ý tưởng khủng khiếp? Có những lựa chọn thay thế tốt hơn (như a man/ infocho các hàm) để cung cấp cho người dùng các hàm Bash với ngữ cảnh bổ sung không?

Lý tưởng nhất là tôi vẫn thích các hướng dẫn sử dụng được đặt gần định nghĩa hàm để mọi người xem mã nguồn cũng nhận được lợi ích, nhưng nếu có cách "phù hợp" để làm điều này thì tôi sẽ mở cho các lựa chọn thay thế.

Chỉnh sửa đây là tất cả các chức năng kiểu trình trợ giúp khá đơn giản và tôi chỉ muốn có thêm một chút bối cảnh tương tác. Chắc chắn đối với các tập lệnh phức tạp hơn mà phân tích các cờ tôi sẽ thêm một --helptùy chọn, nhưng đối với các tập lệnh này sẽ hơi nặng nề khi thêm các cờ trợ giúp vào mọi thứ. Có lẽ đó chỉ là một chi phí tôi nên chấp nhận, nhưng bản :hack này dường như hoạt động khá tốt mà không làm cho nguồn khó hơn nhiều để đọc bản chỉnh sửa của chúng tôi.

Tôi không nghĩ rằng chỉ có một cách tốt để làm điều này.

Nhiều chức năng, tập lệnh và các tệp thực thi khác cung cấp thông báo trợ giúp nếu người dùng cung cấp -hhoặc --helpdưới dạng tùy chọn:

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

Ví dụ:

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

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