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[RW]

Exclude paths.

files[RW]

File paths to search.

ignore[RW]

Ignore paths based on any part of pathname.

labels[RW]

Specific labels to document.

lines[RW]

Number of context lines to display.

output[RW]

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[RW]

Title to use if template can use it.

Public Instance Methods

assemble?(station, options={}) click to toggle source
# 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
current?() click to toggle source

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
document() click to toggle source

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
prerequisite() click to toggle source

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
purge() click to toggle source

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() click to toggle source

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() click to toggle source

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
format(file) click to toggle source

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
output_mapping() click to toggle source

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