From a4e8971b8fb90936b631687117340892a03d2c47 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 10 May 2011 00:54:18 -0400 Subject: [PATCH] lib/rss.rb: Add Documentation --- ChangeLog | 4 +++ lib/rss.rb | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 74 insertions(+), 4 deletions(-) diff --git a/ChangeLog b/ChangeLog index 8695ef9..15bc83c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Tue May 10 10:53:04 2011 Steve Klabnik + + * lib/rss.rb: Add Documentation + Tue May 10 10:53:04 2011 Eric Hodel * common.mk (rdoc): Add rdoc-coverage rule diff --git a/lib/rss.rb b/lib/rss.rb index a1d0f76..a9a8e39 100644 --- a/lib/rss.rb +++ b/lib/rss.rb @@ -1,8 +1,74 @@ -# Copyright (c) 2003-2007 Kouhei Sutou. You can redistribute it and/or -# modify it under the same terms as Ruby. +## +# = RSS reading and writing # -# Author:: Kouhei Sutou -# Tutorial:: http://www.cozmixng.org/~rwiki/?cmd=view;name=RSS+Parser%3A%3ATutorial.en +# Really Simple Sindication (RSS) is a family of formats that describe 'feeds,' +# specially constructed XML documents that allow an interested person to +# subscribe and receive updates from a particular web service. This portion of +# the standard library provides tooling to read and create these feeds. +# +# The standard library supports RSS 0.91, 1.0, 2.0, and Atom, a related format. +# Here are some links to the standards documents for these formats: +# +# * RSS +# * 0.9.1[http://www.rssboard.org/rss-0-9-1-netscape] +# * 1.0[http://web.resource.org/rss/1.0/] +# * 2.0[http://www.rssboard.org/rss-specification] +# * Atom[http://tools.ietf.org/html/rfc4287] +# +# == Consuming RSS +# +# If you'd like to read someone's RSS feed with your Ruby code, you've come to +# the right place. It's really easy to do this, but we'll need the help of +# open-uri: +# +# require 'rss' +# require 'open-uri' +# +# url = 'http://www.ruby-lang.org/en/feeds/news.rss' +# open(url) do |rss| +# feed = RSS::Parser.parse(rss) +# puts "Title: #{feed.channel.title}" +# feed.items.each do |item| +# puts "Item: #{item.title}" +# end +# end +# +# As you can see, the workhorse is RSS::Parser#parse, which takes the source of +# the feed and a parameter that performs validation on the feed. We get back an +# object that has all of the data from our feed, accessable through methods. +# This example shows getting the title out of the channel element, and looping +# through the list of items. +# +# == Producing RSS +# +# Producing our own RSS feeds is easy as well. Let's make a very basic feed: +# +# require "rss" +# +# rss = RSS::Maker.make("atom") do |maker| +# maker.channel.author = "matz" +# maker.channel.updated = Time.now.to_s +# maker.channel.about = "http://www.ruby-lang.org/en/feeds/news.rss" +# maker.channel.title = "Example Feed" +# +# maker.items.new_item do |item| +# item.link = "http://www.ruby-lang.org/en/news/2010/12/25/ruby-1-9-2-p136-is-released/" +# item.title = "Ruby 1.9.2-p136 is released" +# item.updated = Time.now.to_s +# end +# end +# +# puts rss +# +# As you can see, this is a very Builder-like DSL. This code will spit out an +# Atom feed with one item. If we needed a second item, we'd make another block +# with maker.items.new_item and build a second one. +# +# == Copyright +# +# Copyright (c) 2003-2007 Kouhei Sutou. +#-- + require 'rss/1.0' require 'rss/2.0' -- 1.7.0.2