ruby on rails - How do I document Rake tasks with YARD? -

i include information on rake tasks in our rails app. use yard documentation, , @ moment pages lib/tasks/development.rake show default unformatted text.

i can make them render ruby source code using # @markup ruby from yard documentation.

however, renders comments inline, if include yard directives # @!method foo. means the yard documentation on tagging dsls doesn’t seem applicable.

am missing something?

how can yard recognise code vs documentation in .rake files?

n.b. happy solution ignores actual code , generates documentation copy, source documentation copy must .rake file – not want documentation live in separate .markdown file (or whatever) there’s chance of getting out of sync.

more info - yard command:

i using .yardopts file containing following:

--asset graphs 'app/**/*.rb' 'lib/**/*.rb' - readme info/* 

to yard read rake tasks can add 'lib/tasks/*.rake' after hyphen (i.e. add rake files yard ‘files’ list), noted above not process them correctly.

as per benjamin’s suggestion below, tried adding 'lib/tasks/*.rake' before hyphen (i.e. add rake files list of regular ruby files processed), doesn’t seem generate @ all.

it possible yard generating not in expected location / expected filename suppose, i’m not familiar enough how yard works figure out if there orphaned output somewhere. there nothing appropriate coming in search yard generates, , simple find doc | grep rake or find doc | grep basename_of_rake_file doesn’t show anything.

from yard documentation:

in getting started guide yard section under using yard generate documentation, check out documenting files or adding meta-data files. might help.