Can a Rake task be documented with a multiline usage accessible from command line?

user_1307778 0
Viewed 562

Rake allows to document succinctly what tasks are doing. But what if a task is intented to provide more information on its usage? Here is a naive attempt to do it with a multiline desc

desc <<~lid
  Do nothing, even when arguments are provided.
  Usage:
    rake 'users:idle["something", "anotherthing"]'
    rake 'users:idle[, "anotherthing"]' # something is ignored anyway
    rake users:idle # do nothing tersely
lid
task :idle, [:option, :token] => :environment  do |task, fad|
  # Really, do nothing!
end

But running rake --tasks will only reveal the first line. Is there a way to access the rest of the desc through some rake command?

documentation rake ruby
1 Answers

I came here with the same problem: I added a parameter with a default value to task, and wanted to document that in enough detail to make sure that folks knew they could pass their own value.

I found that if I made the string longer, it would print the entire string, wrapping it to the next line, which looks terrible. But if I passed a multiline string, the -T output would only print the string up to the end of the first line.

It turns out, this behavior is intentional:

https://ruby.github.io/rake/Rake/DSL.html#method-i-desc

Descriptions are shown with rake -T (up to the first sentence) and rake -D (the entire description).

Given your example above, rake -D (or rake --describe) should do the trick:

$ rake -T
rake idle[option,token]                # Do nothing, even when arguments are provided

$ rake -D
rake idle[option,token]
    Do nothing, even when arguments are provided.
    Usage:
      rake 'users:idle["something", "anotherthing"]'
      rake 'users:idle[, "anotherthing"]' # something is ignored anyway
      rake users:idle # do nothing tersely
user_104866460
Related