class Detroit::DNote
The Developer Notes tool goes through source files and compiles a list of any labeled comments. Labels are all-caps single word prefixes to a comment ending in a colon and space.
Common labels are ‘TODO`, `FIXME` and `OPTIMIZE`.
Constants
- DEFAULT_FILES
Default glob of files to look in for notes. Presently defaults all Ruby and C scripts (i.e. ‘*.rb` and `*.c` files).
- DEFAULT_LABELS
Default note labels to looked for in source code.
- MANPAGE
Location of manpage for this tool.
Attributes
Exclude paths.
File paths to search.
Ignore paths based on any part of pathname.
Specific labels to document.
Number of context lines to display.
Output is either a file name with a clear extension to infer type or a list of such file names, or a hash mapping file name to type.
@example
output: NOTES.md
@example
output: - NOTES.md - site/notes.html
@example
output: NOTES: markdown site/notes.html: html
Recognized formats include ‘xml`, `html`, `md` and `rdoc` among others.
Title to use if template can use it.
Public Instance Methods
# File lib/detroit-dnote.rb, line 136 def assemble?(station, options={}) return true if station == :document return true if station == :reset return true if station == :purge return false end
Check the output file and see if they are older than the input files.
@return [Boolean] whether output is up-to-date
# File lib/detroit-dnote.rb, line 84 def current? output_mapping.each do |file, format| return false if outofdate?(file, *dnote_session.files) end "DNotes are current (#{output})" end
Generate notes documents.
@return [void]
# File lib/detroit-dnote.rb, line 94 def document session = dnote_session output_mapping.each do |file, format| #next unless verify_format(format) dir = File.dirname(file) mkdir_p(dir) unless File.directory?(dir) session.output = file session.format = format session.run report "Updated #{file.sub(Dir.pwd+'/','')}" end end
Load requirements and set attribute defaults.
@return [void]
# File lib/detroit-dnote.rb, line 34 def prerequisite require 'dnote' require 'dnote/format' @files = DEFAULT_FILES @output = project.log + 'dnotes.html' @labels = nil #DEFAULT_LABELS end
Remove output files.
@return [void]
# File lib/detroit-dnote.rb, line 126 def purge output.each do |file, format| if File.exist?(file) rm(file) report "Removed #{file}" end end end
Reset output files, marking them as out-of-date.
@return [void]
# File lib/detroit-dnote.rb, line 114 def reset output.each do |file, format| if File.exist?(file) utime(0,0,file) report "Marked #{file} as out-of-date." end end end
Private Instance Methods
DNote
Session instance.
@return [DNote::Session]
# File lib/detroit-dnote.rb, line 181 def dnote_session ::DNote::Session.new do |s| s.paths = files s.exclude = exclude s.ignore = ignore s.labels = labels s.title = title s.context = lines s.dryrun = trial? end end
The format of the file based on the extension. If the file has no extension then the value of ‘DEFAULT_FORMAT` is returned.
@return [String]
# File lib/detroit-dnote.rb, line 172 def format(file) type = File.extname(file).sub('.','') type = DEFAULT_FORMAT if type.empty? type end
Convert output into a hash of ‘file => format`.
@todo Should we use apply_naming_policy ?
@return [Hash]
# File lib/detroit-dnote.rb, line 150 def output_mapping @output_mapping ||= ( hash = {} case output when Array output.each do |path| hash[path] = format(path) end when String hash[output] = format(output) when Hash hash = output end hash ) end