Finished documentation of v4 API

4 files changed, 68 insertions, 70 deletions

diff --git a/web/lib/api/v4/josm.rb b/web/lib/api/v4/josm.rb
index 9561bb0..fff32d7 100644
--- a/web/lib/api/v4/josm.rb
+++ b/web/lib/api/v4/josm.rb
@@ -9,14 +9,14 @@ class Taginfo < Sinatra::Base
         },
         :paging => :optional,
         :result => paging_results([
-            [:key,        :STRING, ''],
-            [:value,      :STRING, ''],
-            [:value_bool, :STRING, ''],
-            [:rule,       :STRING, ''],
-            [:area_color, :STRING, ''],
-            [:line_color, :STRING, ''],
-            [:line_width, :INT,    ''],
-            [:icon,       :STRING, '']
+            [:key,        :STRING, 'Key'],
+            [:value,      :STRING, 'Value'],
+            [:value_bool, :STRING, '"yes" or "no". Null if the value is not boolean.'],
+            [:rule,       :STRING, 'JOSM style rule in XML format.'],
+            [:area_color, :STRING, 'Fill color for area (if area rule).'],
+            [:line_color, :STRING, 'Stroke color for line (if line rule).'],
+            [:line_width, :INT,    'Line width (if line rule).'],
+            [:icon,       :STRING, 'Icon path (if icon rule).']
         ]),
         :example => { :style => 'standard', :page => 1, :rp => 10},
         :ui => '/reports/josm_styles'
diff --git a/web/lib/api/v4/key.rb b/web/lib/api/v4/key.rb
index 7374628..f4c3460 100644
--- a/web/lib/api/v4/key.rb
+++ b/web/lib/api/v4/key.rb
@@ -176,13 +176,13 @@ class Taginfo < Sinatra::Base
         },
         :sort => %w( together_count other_key from_fraction ),
         :result => paging_results([
-            [:other_key,      :STRING, ''],
-            [:together_count, :INT,    ''],
-            [:to_fraction,    :FLOAT,  ''],
-            [:from_fraction,  :FLOAT,  '']
+            [:other_key,      :STRING, 'Other key.'],
+            [:together_count, :INT,    'Number of objects that have both keys.'],
+            [:to_fraction,    :FLOAT,  'Fraction of objects with this key that also have the other key.'],
+            [:from_fraction,  :FLOAT,  'Fraction of objects with other key that also have this key.']
         ]),
         :example => { :key => 'highway', :page => 1, :rp => 10, :sortname => 'together_count', :sortorder => 'desc' },
-        :ui => '/keys/highway#keys'
+        :ui => '/keys/highway#combinations'
     }) do
         key = params[:key]
         filter_type = get_filter()
@@ -233,19 +233,19 @@ class Taginfo < Sinatra::Base
         :parameters => { :key => 'Tag key (required)' },
         :paging => :no,
         :result => no_paging_results([
-            [:lang,             :STRING, ''],
-            [:language,         :STRING, ''],
-            [:language_en,      :STRING, ''],
-            [:title,            :STRING, ''],
-            [:description,      :STRING, ''],
-            [:image,            :STRING, ''],
-            [:on_node,          :BOOL,   ''],
-            [:on_way,           :BOOL,   ''],
-            [:on_area,          :BOOL,   ''],
-            [:on_relation,      :BOOL,   ''],
-            [:tags_implies,     :ARRAY_OF_STRINGS, ''],
-            [:tags_combination, :ARRAY_OF_STRINGS, ''],
-            [:tags_linked,      :ARRAY_OF_STRINGS, '']
+            [:lang,             :STRING, 'Language code.'],
+            [:language,         :STRING, 'Language name in its language.'],
+            [:language_en,      :STRING, 'Language name in English.'],
+            [:title,            :STRING, 'Wiki page title.'],
+            [:description,      :STRING, 'Short description of key from wiki page.'],
+            [:image,            :STRING, 'Wiki page title of associated image.'],
+            [:on_node,          :BOOL,   'Is this a key for nodes?'],
+            [:on_way,           :BOOL,   'Is this a key for ways?'],
+            [:on_area,          :BOOL,   'Is this a key for areas?'],
+            [:on_relation,      :BOOL,   'Is this a key for relations?'],
+            [:tags_implies,     :ARRAY_OF_STRINGS, 'List of keys/tags implied by this key.'],
+            [:tags_combination, :ARRAY_OF_STRINGS, 'List of keys/tags that can be combined with this key.'],
+            [:tags_linked,      :ARRAY_OF_STRINGS, 'List of keys/tags related to this key.']
         ]),
         :example => { :key => 'highway' },
         :ui => '/keys/highway#wiki'
@@ -266,14 +266,14 @@ class Taginfo < Sinatra::Base
         },
         :paging => :optional,
         :result => paging_results([
-            [:key,        :STRING, ''],
-            [:value,      :STRING, ''],
-            [:value_bool, :STRING, ''],
-            [:rule,       :STRING, ''],
-            [:area_color, :STRING, ''],
-            [:line_color, :STRING, ''],
-            [:line_width, :INT,    ''],
-            [:icon,       :STRING, '']
+            [:key,        :STRING, 'Key'],
+            [:value,      :STRING, 'Value'],
+            [:value_bool, :STRING, '"yes" or "no". Null if the value is not boolean.'],
+            [:rule,       :STRING, 'JOSM style rule in XML format.'],
+            [:area_color, :STRING, 'Fill color for area (if area rule).'],
+            [:line_color, :STRING, 'Stroke color for line (if line rule).'],
+            [:line_width, :INT,    'Line width (if line rule).'],
+            [:icon,       :STRING, 'Icon path (if icon rule).']
         ]),
         :example => { :style => 'standard', :key => 'highway', :page => 1, :rp => 10},
         :ui => '/keys/highway#josm'
diff --git a/web/lib/api/v4/keys.rb b/web/lib/api/v4/keys.rb
index 0d3f023..3232b95 100644
--- a/web/lib/api/v4/keys.rb
+++ b/web/lib/api/v4/keys.rb
@@ -24,11 +24,10 @@ class Taginfo < Sinatra::Base
             [:count_ways_fraction,      :FLOAT,  'Number of ways in relation to all ways.'],
             [:count_relations,          :INT,    'Number of relations in the OSM database with this key.'],
             [:count_relations_fraction, :FLOAT,  'Number of relations in relation to all relations.'],
-            [:values_all,               :INT,    ''],
-            [:users_all,                :INT,    ''],
-            [:in_wiki,                  :BOOL,   ''],
-            [:in_josm,                  :BOOL,   ''],
-            [:in_potlatch,              :BOOL,   ''],
+            [:values_all,               :INT,    'Number of different values for this key.'],
+            [:users_all,                :INT,    'Number of users owning objects with this key.'],
+            [:in_wiki,                  :BOOL,   'Has this key at least one wiki page?'],
+            [:in_josm,                  :BOOL,   'Is this key referenced in at least one JOSM style rule?']
         ]),
         :example => { :page => 1, :rp => 10, :filter => 'in_wiki', :sortname => 'key', :sortorder => 'asc' },
         :ui => '/keys'
@@ -128,8 +127,7 @@ class Taginfo < Sinatra::Base
                 :values_all               => row['values_all'].to_i,
                 :users_all                => row['users_all'].to_i,
                 :in_wiki                  => row['in_wiki'].to_i     == 1 ? true : false,
-                :in_josm                  => row['in_josm'].to_i     == 1 ? true : false,
-                :in_potlatch              => row['in_potlatch'].to_i == 1 ? true : false,
+                :in_josm                  => row['in_josm'].to_i     == 1 ? true : false
             } 
             h[:wikipages] = row['wikipages'] if row['wikipages']
             h[:prevalent_values] = row['prevalent_values'][0,10] if row['prevalent_values']
@@ -191,14 +189,14 @@ class Taginfo < Sinatra::Base
         :sort => %w( key count_all values_all users_all ),
         :result => paging_results([
             [:key,                :STRING, 'Key'],
-            [:count_all,          :INT,    'Number of occurances in database.'],
-            [:count_all_fraction, :FLOAT,  ''],
+            [:count_all,          :INT,    'Number of objects in database with this key.'],
+            [:count_all_fraction, :FLOAT,  'Fraction of objects in database with this key.'],
             [:values_all,         :INT,    'Number of different values for this key.'],
             [:users_all,          :INT,    'Number of different users who own objects with this key.'],
             [:prevalent_values,   :HASH,   'Often used values.', [
                 [:value,    :STRING, 'Value'],
                 [:count,    :INT,    'Number of occurances of this value.'],
-                [:fraction, :FLOAT,  '']
+                [:fraction, :FLOAT,  'Fraction of all values.']
             ]]
         ]),
         :example => { :min_count => 1000, :english => '1', :page => 1, :rp => 10, :sortname => 'count_all', :sortorder => 'desc' },
diff --git a/web/lib/api/v4/tag.rb b/web/lib/api/v4/tag.rb
index f15b202..609a920 100644
--- a/web/lib/api/v4/tag.rb
+++ b/web/lib/api/v4/tag.rb
@@ -59,11 +59,11 @@ class Taginfo < Sinatra::Base
         },
         :sort => %w( together_count other_tag from_fraction ),
         :result => paging_results([
-            [:other_key,      :STRING, ''],
-            [:other_value,    :STRING, ''],
-            [:together_count, :INT,    ''],
-            [:to_fraction,    :FLOAT,  ''],
-            [:from_fraction,  :FLOAT,  '']
+            [:other_key,      :STRING, 'Other key.'],
+            [:other_value,    :STRING, 'Other value (may be empty).'],
+            [:together_count, :INT,    'Number of objects that have both this tag and other key (or tag).'],
+            [:to_fraction,    :FLOAT,  'Fraction of objects with this tag that also have the other key (or tag).'],
+            [:from_fraction,  :FLOAT,  'Fraction of objects with other key (or tag) that also have this tag.']
         ]),
         :example => { :key => 'highway', :value => 'residential', :page => 1, :rp => 10, :sortname => 'together_count', :sortorder => 'desc' },
         :ui => '/tags/highway=residential#combinations'
@@ -130,19 +130,19 @@ class Taginfo < Sinatra::Base
         :parameters => { :key => 'Tag key (required)', :value => 'Tag value (required).' },
         :paging => :no,
         :result => no_paging_results([
-            [:lang,             :STRING, ''],
-            [:language,         :STRING, ''],
-            [:language_en,      :STRING, ''],
-            [:title,            :STRING, ''],
-            [:description,      :STRING, ''],
-            [:image,            :STRING, ''],
-            [:on_node,          :BOOL,   ''],
-            [:on_way,           :BOOL,   ''],
-            [:on_area,          :BOOL,   ''],
-            [:on_relation,      :BOOL,   ''],
-            [:tags_implies,     :ARRAY_OF_STRINGS, ''],
-            [:tags_combination, :ARRAY_OF_STRINGS, ''],
-            [:tags_linked,      :ARRAY_OF_STRINGS, '']
+            [:lang,             :STRING, 'Language code.'],
+            [:language,         :STRING, 'Language name in its language.'],
+            [:language_en,      :STRING, 'Language name in English.'],
+            [:title,            :STRING, 'Wiki page title.'],
+            [:description,      :STRING, 'Short description of tag from wiki page.'],
+            [:image,            :STRING, 'Wiki page title of associated image.'],
+            [:on_node,          :BOOL,   'Is this a tag for nodes?'],
+            [:on_way,           :BOOL,   'Is this a tag for ways?'],
+            [:on_area,          :BOOL,   'Is this a tag for areas?'],
+            [:on_relation,      :BOOL,   'Is this a tag for relations?'],
+            [:tags_implies,     :ARRAY_OF_STRINGS, 'List of keys/tags implied by this tag.'],
+            [:tags_combination, :ARRAY_OF_STRINGS, 'List of keys/tags that can be combined with this tag.'],
+            [:tags_linked,      :ARRAY_OF_STRINGS, 'List of keys/tags related to this tag.']
         ]),
         :example => { :key => 'highway', :value => 'residential' },
         :ui => '/tags/highway=residential#wiki'
@@ -164,14 +164,14 @@ class Taginfo < Sinatra::Base
         },
         :paging => :optional,
         :result => paging_results([
-            [:key,        :STRING, ''],
-            [:value,      :STRING, ''],
-            [:value_bool, :STRING, ''],
-            [:rule,       :STRING, ''],
-            [:area_color, :STRING, ''],
-            [:line_color, :STRING, ''],
-            [:line_width, :INT,    ''],
-            [:icon,       :STRING, '']
+            [:key,        :STRING, 'Key'],
+            [:value,      :STRING, 'Value'],
+            [:value_bool, :STRING, '"yes" or "no". Null if the value is not boolean.'],
+            [:rule,       :STRING, 'JOSM style rule in XML format.'],
+            [:area_color, :STRING, 'Fill color for area (if area rule).'],
+            [:line_color, :STRING, 'Stroke color for line (if line rule).'],
+            [:line_width, :INT,    'Line width (if line rule).'],
+            [:icon,       :STRING, 'Icon path (if icon rule).']
         ]),
         :example => { :style => 'standard', :key => 'highway', :value => 'residential', :page => 1, :rp => 10},
         :ui => '/tags/highway=residential#josm'