update new podspec help file

lib/cocoapods/command/spec.rb

@@ -437,109 +437,134 @@ module Pod
       def spec_template(data)
         return <<-SPEC
 #
-# Be sure to run `pod spec lint #{data[:name]}.podspec' to ensure this is a
-# valid spec and remove all comments before submitting the spec.
+#  Be sure to run `pod spec lint #{data[:name]}.podspec' to ensure this is a
+#  valid spec and to remove all comments including this before submitting the spec.
 #
-# To learn more about the attributes see http://docs.cocoapods.org/specification.html
+#  To learn more about Podspec attributes see http://docs.cocoapods.org/specification.html
+#  To see working Podspecs in the CocoaPods repo see https://github.com/CocoaPods/Specs/
 #
+
 Pod::Spec.new do |s|
+
+  # ―――  Spec Metadata  ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  These will help people to find your library, and whilst it 
+  #  can feel like a chore to fill in it's definitely to your advantage
+  #
+
   s.name         = "#{data[:name]}"
   s.version      = "#{data[:version]}"
   s.summary      = "#{data[:summary]}"
-  # s.description  = <<-DESC
-  #                   An optional longer description of #{data[:name]}
-  #
-  #                   * Markdown format.
-  #                   * Don't worry about the indent, we strip it!
-  #                  DESC
+
+  s.description  = <<-DESC
+                   A longer description of #{data[:name]} in Markdown format.
+           
+                   * Think: Why did you write this? What is the focus? What does it do? 
+                   * We will be using this to generate tags, and improve search results. 
+                   * Try to keep it short, snappy and to the point.
+                   * Finally, don't worry about the indent, we strip it!
+                   DESC
+
   s.homepage     = "#{data[:homepage]}"
   # s.screenshots  = "www.example.com/screenshots_1", "www.example.com/screenshots_2"
 
-  # Specify the license type. CocoaPods detects automatically the license file if it is named
-  # 'LICENCE*.*' or 'LICENSE*.*', however if the name is different, specify it.
-  s.license      = 'MIT (example)'
-  # s.license      = { :type => 'MIT (example)', :file => 'FILE_LICENSE' }
 
-  # Specify the authors of the library, with email addresses. You can often find
-  # the email addresses of the authors by using the SCM log. E.g. $ git log
+  # ―――  Spec License  ――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
   #
-  s.author       = { "#{data[:author_name]}" => "#{data[:author_email]}" }
-  # s.authors      = { "#{data[:author_name]}" => "#{data[:author_email]}", "other author" => "and email address" }
+  #  Licensing your code is important.
+  #  CocoaPods will detect a license file if there is a named LICENSE*
+  #  
+
+  s.license      = 'MIT'
+  # s.license      = { :type => 'MIT', :file => 'FILE_LICENSE' }
+
+
+  # ――― Author Metadata  ――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
   #
-  # If absolutely no email addresses are available, then you can use this form instead.
+  #  Specify the authors of the library, with email addresses. Email addresses of the authors
+  #  by using the SCM log. E.g. $ git log. If no email can be found we accept just the names.
   #
-  # s.author       = '#{data[:author_name]}', 'other author'
 
-  # Specify the location from where the source should be retrieved.
-  #
-  s.source       = { :git => "#{data[:source_url]}", #{data[:ref_type]} => "#{data[:ref]}" }
+  s.author       = { "#{data[:author_name]}" => "#{data[:author_email]}" }
+  # s.authors      = { "#{data[:author_name]}" => "#{data[:author_email]}", "other author" => "email@address.com" }
+  # s.author       = '#{data[:author_name]}', 'other author'
 
 
-  # If this Pod runs only on iOS or OS X, then specify the platform and
-  # the deployment target.
+  # ――― Platform Specifics ――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  # 
+  #  If this Pod runs only on iOS or OS X, then specify the platform and
+  #  the deployment target. You can optionally include the target after the platform.
   #
-  # s.platform     = :ios, '5.0'
 
-  # ――― MULTI-PLATFORM VALUES ――――――――――――――――――――――――――――――――――――――――――――――――― #
+  # s.platform     = :ios
+  # s.platform     = :ios, '5.0'
 
-  # If this Pod runs on both platforms, then specify the deployment
-  # targets.
-  #
+  # For multiple platforms
   # s.ios.deployment_target = '5.0'
   # s.osx.deployment_target = '10.7'
 
-  # A list of file patterns which select the source files that should be
-  # added to the Pods project. If the pattern is a directory then the
-  # path will automatically have '*.{h,m,mm,c,cpp}' appended.
-  #
-  s.source_files = 'Classes', 'Classes/**/*.{h,m}'
-  s.exclude_files = 'Classes/Exclude'
 
-  # A list of file patterns which select the header files that should be
-  # made available to the application. If the pattern is a directory then the
-  # path will automatically have '*.h' appended.
+  # ――― Source Location ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
   #
-  # If you do not explicitly set the list of public header files,
-  # all headers of source_files will be made public.
+  #  Specify the location from where the source should be retrieved. 
+  #  Supports git, hg, svn and HTTP
   #
+
+  s.source       = { :git => "#{data[:source_url]}", #{data[:ref_type]} => "#{data[:ref]}" }
+
+
+  # ――― Source Code ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #  
+  #  CocoaPods is smart about how it include source code, for source files
+  #  giving a folder will include any h, m, mm, c & cpp files. For header 
+  #  files it will include any header in the folder.
+  #  Not including the public_header_files will make all headers public.
+  #
+
+  s.source_files  = 'Classes', 'Classes/**/*.{h,m}'
+  s.exclude_files = 'Classes/Exclude'
+
   # s.public_header_files = 'Classes/**/*.h'
 
-  # A list of resources included with the Pod. These are copied into the
-  # target bundle with a build phase script.
+
+  # ――― Resources ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  A list of resources included with the Pod. These are copied into the
+  #  target bundle with a build phase script. Anything else will be cleaned.
+  #  You can preserve files from being cleaned, please don't preserve 
+  #  non-essential files like tests, examples and documentation.
   #
+
   # s.resource  = "icon.png"
   # s.resources = "Resources/*.png"
 
-  # A list of paths to preserve after installing the Pod.
-  # CocoaPods cleans by default any file that is not used.
-  # Please don't include documentation, example, and test files.
-  #
   # s.preserve_paths = "FilesToSave", "MoreFilesToSave"
 
-  # Specify a list of frameworks that the application needs to link
-  # against for this Pod to work.
-  #
+
+  # ――― Project Linking ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #  
+  #  Link your library with frameworks, or libraries. Libraries do not include
+  #  the lib prefix of their name.
+  #   
+
   # s.framework  = 'SomeFramework'
   # s.frameworks = 'SomeFramework', 'AnotherFramework'
 
-  # Specify a list of libraries that the application needs to link
-  # against for this Pod to work.
-  #
   # s.library   = 'iconv'
   # s.libraries = 'iconv', 'xml2'
 
-  # If this Pod uses ARC, specify it like so.
-  #
-  s.requires_arc = true
 
-  # If you need to specify any other build settings, add them to the
-  # xcconfig hash.
-  #
-  # s.xcconfig = { 'HEADER_SEARCH_PATHS' => '$(SDKROOT)/usr/include/libxml2' }
+  # ――― Project Settings ――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  # 
+  #  If your library depends on compiler flags you can set them in the xcconfig hash
+  #  where they will only apply to your library. If you depend on other Podspecs 
+  #  you can include multiple dependencies to ensure it works.
 
-  # Finally, specify any Pods that this Pod depends on.
-  #
+  # s.requires_arc = true
+
+  # s.xcconfig = { 'HEADER_SEARCH_PATHS' => '$(SDKROOT)/usr/include/libxml2' }
   # s.dependency 'JSONKit', '~> 1.4'
+
 end
       SPEC
     end