docstat 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: df01644c316c2876021d45299e9dcf1dca78b826
+  data.tar.gz: 996f490dd4e4bed15e86d4aea9d40cf2c0d14fca
+SHA512:
+  metadata.gz: fd02e766736729bad497005e67b6671815d8d52832f5091b491f0dd2dde9b0cc896db49cff4e95b3c30ae81cb9a639ec7644de044b1f0574ec52ada58896defc
+  data.tar.gz: f97ebd1de84def67a09c7581b3fc9a78ce61c91dac94da897f674c3741e139be81d6d5fe183e2e6704060141a28b9439b797ab4ffb29e5231f7b59f450da3bbc

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 1.0.0
+
+* Initial version

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Delisa Mason
+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,53 @@
+# docstat [![Build Status](https://travis-ci.org/kattrali/docstat.svg?branch=master)](https://travis-ci.org/kattrali/docstat)
+
+Documentation metrics for libraries, optimized for Cocoa. `docstat` takes documentation sets (*.docset) generated via `appledoc` and similar tools and extracts general statistics. It also includes a binary for testing that coverage exceeds a given ratio.
+
+## Usage
+
+### Printing token statistics
+
+The included `docstat` binary prints the number of tokens and coverage in a given documentation set
+
+### Testing for coverage
+
+The included `docstat-test` binary tests a given documentation set for a specified coverage level:
+
+    $ docstat-test [docset path] (expected coverage ratio)
+
+If no expected coverage ratio is specified, the default is '0.9'. On failure, the process exits with a status code of 1.
+
+### Processing coverage data
+
+`DocStat.process(docset_path)` returns a Hash containing information about all of the documented tokens in the following structure:
+
+```ruby
+{
+  'ratio': decimal
+  'containers': [
+    {
+      'name': 'class name',
+      'ratio': decimal,
+      'tokens': [
+        {
+          'name': 'name of token',
+          'type': 'property or message type',
+          'abstract': 'description of token',
+          'declaration': 'formal declaration',
+          'returns': 'description of return value',
+          'documented': boolean
+        }, ...
+      ]
+    }, ...
+  ]
+}
+```
+
+## Installation
+
+Run `gem install docstat` in a terminal. `docstat` depends on the `sqlite3` ruby library.
+
+## Development
+
+`docstat` is tested using [bacon](https://github.com/chneukirchen/bacon).
+
+Install development dependencies via `bundle install`.

data/bin/docstat

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.dirname(__FILE__), '../lib/docstat'))
+
+if docset_path = ARGV[0]
+  stats  = DocStat.process(docset_path)
+  tokens = stats['containers'].map {|c| c['tokens']}.flatten
+  ratio  = stats['ratio']
+  print "#{tokens.size} tokens, #{((ratio*1000).to_i/1000.0) * 100}% documented"
+else
+  print "No Documentation Set (*.docset) directory specified\n"
+  exit(1)
+end

data/lib/docstat/container.rb

@@ -0,0 +1,67 @@
+$:.unshift File.expand_path('..', __FILE__)
+
+require 'token'
+
+module DocStat
+  class Container
+    attr_reader :name, :tokens
+
+    QUERY = "select ZCONTAINERNAME,ZTOKENNAME,ZTYPENAME,ZTOKENMETAINFORMATION.ZABSTRACT,ZDECLARATION,ZRETURNVALUE.ZABSTRACT from ZTOKEN \
+      inner join ZCONTAINER on ZTOKEN.ZCONTAINER = ZCONTAINER.Z_PK \
+      inner join ZTOKENTYPE on ZTOKEN.ZTOKENTYPE = ZTOKENTYPE.Z_PK \
+      inner join ZTOKENMETAINFORMATION on ZTOKEN.Z_PK = ZTOKENMETAINFORMATION.ZTOKEN \
+      left join ZRETURNVALUE on (ZTOKENMETAINFORMATION.ZRETURNVALUE = ZRETURNVALUE.Z_PK) \
+      order by ZCONTAINERNAME"
+
+    def self.from_sqlite path
+      db = SQLite3::Database.new(path)
+      rows = db.execute(QUERY).to_a
+      container_groups = rows.group_by {|r| r.first }
+      groups = container_groups.map do |name, tokens|
+        self.new(name, tokens)
+      end
+      db.close
+      groups
+    end
+
+    def initialize name, tokens
+      @name, @tokens = name, tokens.map {|t| Token.new(t)}
+    end
+
+    def to_hash
+      {
+        "name"   => name,
+        "tokens" => tokens.map(&:to_hash),
+        "ratio"  => ratio
+      }
+    end
+
+    def ratio
+      documentation_ratio(tokens)
+    end
+
+    def method_documentation_ratio
+      documentation_ratio(tokens.select(:method?))
+    end
+
+    def property_documentation_ratio
+      documentation_ratio(tokens.select(:property?))
+    end
+
+    def description
+      token_description = tokens.map {|t| t.description}.join("\n")
+      "#{name}:\n#{token_description}"
+    end
+
+    private
+
+    def documentation_ratio token_set
+      if token_set.size > 0
+        documented = token_set.select(&:documented?)
+        documented.size.to_f / token_set.size
+      else
+        1
+      end
+    end
+  end
+end

data/lib/docstat/token.rb

@@ -0,0 +1,53 @@
+
+module DocStat
+  class Token
+    attr_reader :name, :type, :abstract, :declaration, :return_value
+
+    METHOD_TYPES   = ['clm','clfm','instm','intfm']
+    PROPERTY_TYPES = ['instp','intfp']
+    TYPE_MAPPING = {
+      'clm' => 'class method',
+      'clfm' => 'class category method',
+      'instm' => 'instance method',
+      'intfm' => 'instance method',
+      'instp' => 'instance property',
+      'intfp' => 'instance property'
+    }
+
+    def initialize property_ary
+      _, @name, @type, @abstract, @declaration, @return_value = *property_ary
+    end
+
+    def to_hash
+      {
+        "name" => name,
+        "type" => pretty_type,
+        "abstract" => abstract,
+        "declaration" => declaration,
+        "returns" => return_value,
+        "documented" => documented?
+      }
+    end
+
+    def documented?
+      # TODO: check parameter docs as well?
+      !((abstract.nil? || abstract.empty?) && (return_value.nil? || return_value.empty?))
+    end
+
+    def method?
+      METHOD_TYPES.include?(type)
+    end
+
+    def property?
+      PROPERTY_TYPES.include?(type)
+    end
+
+    def pretty_type
+      TYPE_MAPPING[type]
+    end
+
+    def description
+      "#{name} (#{type}) - #{abstract}"
+    end
+  end
+end

data/lib/docstat.rb

@@ -0,0 +1,57 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+
+require 'sqlite3'
+require 'docstat/container'
+
+module DocStat
+
+  # Parses a docset and returns a representation of the
+  # documented tokens within the library.
+  # The general structure is as follows:
+  #
+  # {
+  #   'ratio': decimal
+  #   'containers': [
+  #     {
+  #       'name': 'class name',
+  #       'ratio': decimal
+  #       'tokens': [
+  #         {
+  #           'name': 'name of token',
+  #           'type': 'property or message type',
+  #           'abstract': 'description of token',
+  #           'declaration': 'formal declaration',
+  #           'returns': 'description of return value',
+  #           'documented': boolean
+  #         }, ...
+  #       ]
+  #     }, ...
+  #   ]
+  # }
+  def self.process docset_path
+    containers = containers_from_docset(docset_path)
+    { "containers" => containers.map(&:to_hash) , "ratio" => overall_ratio(containers) }
+  end
+
+  def self.test_ratio docset_path, passing_ratio
+    containers = containers_from_docset(docset_path)
+    overall_ratio(containers) >= passing_ratio
+  end
+
+  private
+
+  def self.containers_from_docset docset_path
+    db_path = File.join(docset_path, 'Contents/Resources/docSet.dsidx')
+    Container.from_sqlite(db_path)
+  end
+
+  def self.overall_ratio containers
+    tokens = containers.map(&:tokens).flatten
+    if tokens.size > 0
+      overall_ratio = tokens.select(&:documented?).size.to_f/tokens.size
+    else
+      overall_ratio = 1
+    end
+    overall_ratio
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: docstat
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Delisa Mason
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bacon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Coverage statistics for Cocoa documentation sets
+email:
+- iskanamagus@gmail.com
+executables:
+- docstat
+extensions: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+files:
+- Gemfile
+- LICENSE
+- CHANGELOG.md
+- README.md
+- bin/docstat
+- lib/docstat.rb
+- lib/docstat/container.rb
+- lib/docstat/token.rb
+homepage: https://github.com/docstat
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.6
+signing_key: 
+specification_version: 4
+summary: A command-line utility for checking the documentation coverage of a Cocoa
+  library
+test_files: []
+has_rdoc: