writing docs

README.rdoc

@@ -6,7 +6,54 @@
 
 == Description
 
-Description goes here.
+This is gem designed to parse eLibri generated onix files.
+If you don't have access to eLibri api, but you still want to make some us of it - check elibri_onix_mocks gem for mocks and examples of using it.
+
+== Usage
+
+Usage depends on what you want to parse. In normal usage, when you received response from eLibri server you want to parse it using ONIXMessage class. Therefore you need to execute:
+
+Elibri::ONIX::Release_3_0::ONIXMessage.new(xml_data)
+
+xml_data should be string containing ONIX xml you want to parse.
+
+Creating a new ONIXMessage object will also create embedded objects inside - representing structure of xml file.
+ONIXMessage -> many Product(s)
+  Product -> many ProductIdentifier(s)
+  Product -> many RelatedProduct(s)
+    RelatedProduct -> many ProductIdentifier(s)
+  Product -> many SupplyDetail(s)
+    SupplyDetail -> one Supplier
+    SupplyDetail -> one Price
+    SupplyDetail -> one StockQuantityCoded
+  Product -> many Measure(s)
+  Product -> many TitleDetail(s)
+    TitleDetail -> many TitleElement(s)
+  Product -> many Collection(s)
+    Collection -> many TitleElement(s)
+    Collection -> one TitleDetail
+  Product -> many Contributor(s)
+  Product -> many Language(s)
+  Product -> many Extent(s)
+  Product -> many Subject(s)
+  Product -> many AudienceRange(s)
+  Product -> many TextContent(s)
+  Product -> many SupportingResource(s)
+  Product -> one Imprint
+  Product -> one Publisher
+  Product -> one PublishingDate
+  Product -> many SalesRestriction(s)
+ONIXMessage -> one Header
+  Header -> one Sender
+
+
+However if you have only fragment of xml that you want to parse - for example Contributor, you may parse only this fragment invoking constructor of appropriate class, providing xml as an argument, for example:
+
+Elibri::ONIX::Release_3_0::Contributor.new(xml_data)
+
+Each object provide method to_xml which will return xml used to construct it.
+
+Object contains attributes, which are represented by instance variables. You can see list of attributes in FIELDS file.
 
 == Contributing to elibri_onix
 

elibri_onix.gemspec

@@ -2,8 +2,8 @@
 require File.expand_path('../lib/elibri_onix/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Marcin Urbanski"]
-  gem.email         = ["marcin@urbanski.vdl.pl"]
+  gem.authors       = ["Marcin Urbanski", "Piotr Szmielew"]
+  gem.email         = ["marcin@urbanski.vdl.pl", "p.szmielew@ava.waw.pl"]
   gem.description   = %q{EDItEUR ONIX format subset implementation used in Elibri publication system}
   gem.summary       = %q{EDItEUR ONIX format subset implementation used in Elibri publication system}
   gem.homepage      = "http://github.com/elibri/elibri_onix"

lib/elibri_onix/onix_3_0/audience_range.rb

@@ -5,6 +5,9 @@ module Release_3_0
 
       class AudienceRange
 
+        #from ONIX documentation:
+        #An optional and repeatable group of data elements which together describe an audience or readership range for which a product is intended.
+
         ATTRIBUTES = [
           :qualifier, :precision, :value
         ]

lib/elibri_onix/onix_3_0/extent.rb

@@ -5,6 +5,10 @@ module ONIX
     module Release_3_0
 
       class Extent
+
+        #from ONIX documentation:
+        #covers product extents, in terms of pages, running times, file sizes etc, as may be appropriate to each media type.
+        #For products whose content is primarily readable text, it also covers illustrations and other kinds of ancillary matter such as the inclusion of a bibliography or index.
 
         ATTRIBUTES = [
           :type, :value, :unit, :type_name, :unit_name

lib/elibri_onix/onix_3_0/onix_message.rb

@@ -5,7 +5,9 @@ module Release_3_0
 
       class ONIXMessage        
         attr_accessor :release, :elibri_dialect, :products, :header, :to_xml
-
+
+        #class representing whole ONIX response from eLibri server
+
         ATTRIBUTES = [
           :release, :elibri_dialect, :header
         ]

lib/elibri_onix/onix_3_0/product.rb

@@ -5,7 +5,10 @@ module Release_3_0
 
       class Product
 
-
+        #class representing one Product from eLibri.
+        #important thing - record reference is unique eLibri identifier
+
+
         ATTRIBUTES =
         [
           :elibri_dialect, :height, :width, :thickness, :weight, :ean, :isbn13, :number_of_pages, :duration, 

lib/elibri_onix/onix_3_0/related_product.rb

@@ -8,6 +8,7 @@ module Release_3_0
 
       class RelatedProduct
 
+
         ATTRIBUTES = [
           :relation_code, :proprietary_identifiers, :record_reference
         ]