Class: Detroit::DNote

Inherits:
Tool
  • Object
show all
Includes:
Standard
Defined in:
lib/detroit-dnote.rb

Overview

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`.

Constant Summary collapse

MANPAGE =

Location of manpage for this tool.

File.dirname(__FILE__) + '/../man/detroit-dnote.5'
DEFAULT_FILES =

Default glob of files to look in for notes. Presently defaults all Ruby and C scripts (i.e. ‘*.rb` and `*.c` files).

"**/*.{rb,c}"
DEFAULT_LABELS =

Default note labels to looked for in source code.

['TODO', 'FIXME', 'OPTIMIZE', 'DEPRECATE']

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#exclude ⇒ Object

Exclude paths.



50
51
52
 
# File 'lib/detroit-dnote.rb', line 50

def exclude
  @exclude
end

#files ⇒ Object

File paths to search.



47
48
49
 
# File 'lib/detroit-dnote.rb', line 47

def files
  @files
end

#ignore ⇒ Object

Ignore paths based on any part of pathname.



53
54
55
 
# File 'lib/detroit-dnote.rb', line 53

def ignore
  @ignore
end

#labels ⇒ Object

Specific labels to document.



44
45
46
 
# File 'lib/detroit-dnote.rb', line 44

def labels
  @labels
end

#lines ⇒ Object

Number of context lines to display.



59
60
61
 
# File 'lib/detroit-dnote.rb', line 59

def lines
  @lines
end

#output ⇒ Object

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.

Recognized formats include ‘xml`, `html`, `md` and `rdoc` among others.

Examples:

output: NOTES.md
output:
  - NOTES.md
  - site/notes.html
output:
  NOTES: markdown
  site/notes.html: html


78
79
80
 
# File 'lib/detroit-dnote.rb', line 78

def output
  @output
end

#title ⇒ Object

Title to use if template can use it.



56
57
58
 
# File 'lib/detroit-dnote.rb', line 56

def title
  @title
end

Instance Method Details

#assemble?(station, options = {}) ⇒ Boolean

Returns:

  • (Boolean) 


136
137
138
139
140
141
 
# 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? ⇒ Boolean

Check the output file and see if they are older than the input files.

Returns:

  • (Boolean) —

    whether output is up-to-date



84
85
86
87
88
89
 
# 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 ⇒ void

This method returns an undefined value.

Generate notes documents.



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# 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 ⇒ void

This method returns an undefined value.

Load requirements and set attribute defaults.



34
35
36
37
38
39
40
41
 
# 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 ⇒ void

This method returns an undefined value.

Remove output files.



126
127
128
129
130
131
132
133
 
# 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 ⇒ void

This method returns an undefined value.

Reset output files, marking them as out-of-date.



114
115
116
117
118
119
120
121
 
# 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