From 792ef240184aa017f652a8755b8042ff2fd46a0f Mon Sep 17 00:00:00 2001
From: Joshua Peek <josh@joshpeek.com>
Date: Tue, 24 May 2011 20:39:27 -0500
Subject: [PATCH] Document Pathname

---
 lib/linguist/pathname.rb | 78 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/lib/linguist/pathname.rb b/lib/linguist/pathname.rb
index 44dadd2c..56b3a248 100644
--- a/lib/linguist/pathname.rb
+++ b/lib/linguist/pathname.rb
@@ -2,15 +2,45 @@ require 'linguist/language'
 require 'linguist/mime'
 
 module Linguist
+  # Similar to ::Pathname, Linguist::Pathname wraps a path string and
+  # provides helpful query methods. Its useful when you only have a
+  # filename but not a blob and need to figure out the langauge of the file.
   class Pathname
+    # Public: Initialize a Pathname
+    #
+    # path - A filename String. The file may or maybe actually exist.
+    #
+    # Returns a Pathname.
     def initialize(path)
       @path = path
     end
 
+    # Public: Get the basename of the path
+    #
+    # Examples
+    #
+    #   Pathname.new('sub/dir/file.rb').basename
+    #   # => 'file.rb'
+    #
+    # Returns a String.
     def basename
       File.basename(@path)
     end
 
+    # Public: Get the extname of the path
+    #
+    # Examples
+    #
+    #   Pathname.new('.rb').extname
+    #   # => '.rb'
+    #
+    #   Pathname.new('file.rb').extname
+    #   # => '.rb'
+    #
+    #   Pathname.new('Rakefile').extname
+    #   # => 'Rakefile'
+    #
+    # Returns a String.
     def extname
       if basename[0] == ?.
         basename
@@ -21,26 +51,74 @@ module Linguist
       end
     end
 
+    # Public: Get the language of the path
+    #
+    # The path extension name is the only heuristic used to detect the
+    # language name.
+    #
+    # Examples
+    #
+    #   Pathname.new('file.rb').language
+    #   # => Language['Ruby']
+    #
+    # Returns a Langauge.
     def language
       Language.find_by_extension(extname) || Language['Text']
     end
 
+    # Deprecated: Get the lexer of the path
+    #
+    # Returns a Lexer.
     def lexer
       language.lexer
     end
 
+    # Public: Get the mime type
+    #
+    # Examples
+    #
+    #   Pathname.new('index.html').mime_type
+    #   # => 'text/html'
+    #
+    # Returns a mime type String.
     def mime_type
       @mime_type ||= Mime.mime_for(extname)
     end
 
+    # Public: Get the mime media type
+    #
+    # Examples
+    #
+    #   Pathname.new('index.html').media_type
+    #   # => 'text'
+    #
+    # Returns a media type String.
     def media_type
       mime_type.split('/')[0]
     end
 
+    # Public: Get the mime sub type
+    #
+    # Examples
+    #
+    #   Pathname.new('index.html').sub_type
+    #   # => 'html'
+    #
+    # Returns a media type String.
     def sub_type
       mime_type.split('/')[1]
     end
 
+    # Public: Get the Content-Type header
+    #
+    # This value is used when serving raw blobs.
+    #
+    # Examples
+    #
+    #   Pathname.new('file.txt').content_type
+    #   # => 'text/plain; charset=utf-8'
+    #
+    # Returns a content type String.
     def content_type
       @content_type ||= Mime.content_type_for(extname)
     end