yard-notes 0.1.0

data/.ruby

@@ -0,0 +1,44 @@
+---
+source:
+- meta
+authors:
+- name: Trans
+  email: transfire@gmail.com
+copyrights:
+- holder: Rubyworks
+  year: '2011'
+  license: MIT
+requirements:
+- name: yard
+dependencies: []
+alternatives:
+- dnote
+conflicts: []
+repositories:
+- uri: git://github.com/rubyworks/yard-notes.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubyworks.github.com/yard-notes
+  code: http://github.com/rubyworks/yard-notes
+  bugs: http://github.com/rubyworks/yard-notes/issues
+  mail: http://groups.google.com/groups/rubyworks-mailinglist
+  chat: irc://chat.us.freenode.net/rubyworks
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2011-06-11'
+summary: Because some tags are for project developers, not API users.
+title: YARD Notes
+version: 0.1.0
+name: yard-notes
+description: ! 'Normally YARD emits a warning about unrecongnized decoumentaiton tags
+
+  and omits them from output. With YARD Notes, all caps tags will still
+
+  be omitted from the docs, but will be added to a special NOTES file of
+
+  the documentation.'
+organization: rubyworks
+date: '2012-03-05'

data/.yardopts

@@ -0,0 +1,9 @@
+--title "YARD Notes"
+--readme README.md
+--output-dir web/doc
+--plugin notes
+--private
+lib/*.rb 
+-
+[A-Z]*.*
+

data/License.txt

@@ -0,0 +1,20 @@
+The MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/Notice.txt

@@ -0,0 +1,22 @@
+YARD
+
+Copyright (c) 2007-2011 Loren Segal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,47 @@
+# YARD Notes
+
+[Hompage](http://rubyworks.github.com/yard-notes) /
+[Report Issue](http://github.com/rubyworks/yard-notes/issues) /
+[Source Code](http://githubc.com/rubyworks/yard-notes)
+[Mailing List](http://groups.google.com/groups/rubyworks-mailinglist) /
+[IRC Chat](irc://chat.us.freenode.net/rubyworks)
+
+
+## Description
+
+YARD likes to inform us of every line in every file where
+a tag is used that hasn't been explicitly informed shoud
+exist. The way I figure it, if I used it, it should exist.
+However, that doesn't mean I neccessiarily want all tags to
+show up in the docs, so this plugin keeps YARD from making
+a ruckess about tags in ALL CAPS, keeps such tags out of the
+docs, and adds them to a specia NOTES pages where they can
+be reviewed. This is a great way to make development notes
+in your code.
+
+
+## Instruction
+
+Use yard as usual but add the `--plugin notes` command line
+option.
+
+    $ yard --plugin ntoes ...
+
+
+## Installation
+
+Using RubyGems to install:
+
+    $ gem install yard-shutup
+
+
+## Copyright & License
+
+(MIT License)
+
+Copyright (c) 2011 Rubyworks.
+
+YARD Notes is distributable under the terms of the **MIT** license.
+
+See License.txt for details.
+

data/lib/yard-notes.rb

@@ -0,0 +1,148 @@
+# @TODO Add command option to turn warnings back on.
+
+module YARD
+
+  module Tags
+
+    # Alternate factory in which ...
+    #
+    # @NOTE I have a feeling this might all end up here once
+    #       lsegal sees what his code is actually doing.
+    class AutoFactory < DefaultFactory
+    end
+
+    class Library
+      class << self
+        # Sets the list of tags that are not explicitly defined by the 
+        # YARD proper, nor by the user on the cammnd line via `--tag`.
+        # These tags are recorded as "developer's tags" and not
+        # displayed in the general documentation.
+        #
+        # @return [Array<Symbol>] list of transitive tags
+        attr_accessor :developers_tags
+      end
+
+      self.developers_tags = []
+
+      # If tag is missing then auto-define it.
+      #
+      # @TODO This is an example.
+      def respond_to?(tag_method)
+        if md = /_tag$/.match(tag_method.to_s)
+          tag_name = md.pre_match
+          if /^[A-Z]+$/ =~ tag_name
+            Tags::Library.define_tag(tag_name.to_s.capitalize, tag_name)
+            Tags::Library.developers_tags |= [tag_name]
+            true
+          else
+            super(tag_method)
+          end
+        else
+          super(tag_method)
+        end
+      end
+    end
+
+  end
+
+  module CodeObjects
+    class NotesFileObject < ExtraFileObject
+      #
+      def initialize
+        self.filename   = 'NOTES.md'
+        self.name       = 'NOTES'
+        self.attributes = SymbolHash.new(false)
+      end
+
+      # Lazily produce contents.
+      def contents
+        @contents ||= (
+          text  = ["# Developer's Notes"]
+          sort  = Hash.new{ |h,k| h[k] = [] }
+          dtags = Tags::Library.developers_tags
+
+          Registry.each do |code_object|
+            code_object.tags.each do |tag|
+              next unless dtags.include?(tag.tag_name)
+              sort[tag.tag_name] << tag
+            end
+          end
+
+          sort.each do |name, tags|
+            text << "## #{name}"
+            tags.each do |tag|
+              text << "* #{tag.text} (#{tag.object})"
+            end
+          end
+
+          parse_contents(text.join("\n\n"))
+        )
+      end
+
+      # This method was taken directly from YARD and change by removing `self.`
+      # from `contents`, so that it can be lazily created.
+      #
+      # @param [String] data
+      #   The file contents
+      #
+      # @return [String] content
+      def parse_contents(data)
+        retried = false
+        cut_index = 0
+        data = data.split("\n")
+        data.each_with_index do |line, index|
+          case line
+          when /^#!(\S+)\s*$/
+            if index == 0
+              attributes[:markup] = $1
+            else
+              cut_index = index
+              break
+            end
+          when /^\s*#\s*@(\S+)\s*(.+?)\s*$/
+            attributes[$1] = $2
+          else
+            cut_index = index
+            break
+          end
+        end
+        data = data[cut_index..-1] if cut_index > 0
+        contents = data.join("\n")
+        if contents.respond_to?(:force_encoding) && attributes[:encoding]
+          begin
+            contents.force_encoding(attributes[:encoding])
+          rescue ArgumentError
+            log.warn "Invalid encoding `#{attributes[:encoding]}' in #{filename}"
+          end
+        end
+        return contents
+      rescue ArgumentError => e
+        if retried && e.message =~ /invalid byte sequence/
+          # This should never happen.
+          log.warn "Could not read #{filename}, #{e.message}. You probably want to set `--charset`."
+          contents = ''
+          return
+        end
+        data.force_encoding('binary') if data.respond_to?(:force_encoding)
+        retried = true
+        retry
+      end
+
+    end
+
+  end
+
+  module CLI
+    class Yardoc
+      alias run_without_notes run
+      def run(*args)
+        @options[:files] << CodeObjects::NotesFileObject.new
+        run_without_notes(*args)
+      end
+    end
+  end
+
+end
+
+YARD::Tags::Library.default_factory = YARD::Tags::AutoFactory.new
+

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: yard-notes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Trans
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &30883380 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *30883380
+description: ! 'Normally YARD emits a warning about unrecongnized decoumentaiton tags
+
+  and omits them from output. With YARD Notes, all caps tags will still
+
+  be omitted from the docs, but will be added to a special NOTES file of
+
+  the documentation.'
+email:
+- transfire@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- Notice.txt
+- License.txt
+- README.md
+files:
+- .yardopts
+- .ruby
+- lib/yard-notes.rb
+- Notice.txt
+- README.md
+- License.txt
+homepage: http://rubyworks.github.com/yard-notes
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Because some tags are for project developers, not API users.
+test_files: []