yard-gobject 0.0.2 → 0.0.3

data/README.md

@@ -15,11 +15,22 @@ For now, it supports only one tag: <code>@properties</code>. This tag can be app
 
 **Syntax**
 
-    # @properties property-name [PropertyType] description,
+    # @properties property-name [PropertyType] :PropertyAccess description,
     # another-property [PropertyType] description...
 
+<code>:PropertyAccess</code> is used to represent the access to the properties. Only three access permissions are used. The order in which they appear is unimportant. The letters used for specifying the position are as follows:
+
+  + **R** — for Read
+  + **W** — for Write
+  + **C** — for Construct
+
 <code>PropertyType</code> is formatted the same way YARD formats types. <code>description</code> can be ommited.
 
+
+***An example:***
+    ##
+    # @properties uri [String] :RWC, visible [String] :RWC
+
 License
 -------
 

data/templates/default/fulldoc/html/css/common.css

@@ -24,6 +24,12 @@
   color: gray;
 }
 
+.tags ul.gobject_properties li .access {
+  font-family: monospace;
+  margin-left: 20px;
+  color: black;
+}
+
 .tags ul.gobject_properties li .description {
   display: block;
   margin: 0.45em auto auto 35px;

data/templates/default/tags/html/properties.erb

@@ -6,6 +6,7 @@
     <li>
       <span class="name"><%= prop[:name] %></span>
       <span class="type"><%= format_types prop[:type] %></span>
+      <span class="access"><%= format_gobject_property_access(prop) %>
       <% if !prop[:description].nil? and !prop[:description].empty? %>
       <span class="description"><%= htmlify_line prop[:description] %></span>
       <% end %>

data/yard-gobject.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{yard-gobject}
-  s.version = "0.0.2"
+  s.version = "0.0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Stojan Dimitrovski"]

data/yard-gobject.rb

@@ -35,6 +35,29 @@ YARD::Templates::Engine.register_template_path(template_dir)
 YARD::Tags::Library.define_tag("GObject Properties", :properties)
 
 module YARD::Templates::Helpers::HtmlHelper
+  # extracts the GObject properties from a {YARD::Tags::Tag}
+  #
+  # The syntax of the +@properties+ tag is as follows:
+  #
+  # +property_name+ can be any name containing any letter, underscore
+  # or dash. Please note that dashes will be automatically converted
+  # to underscores.
+  #
+  # +PropertyType+ can be any Ruby Object that best fits the GType used
+  # in the GObject property.
+  #
+  # +:PropertyAccess+ represents the permissions associated with a
+  # property. They can be either *R*, for Read, *W*, for Write, and
+  # *C*, for Construct. Their order is unimportant. It is, however,
+  # important that they are preceeded by the column (:) character.
+  #
+  # desc is any description that you might want to add to this
+  # property. It can be ommited.
+  #
+  # @example
+  #   # @properties uri [String] :RW, visible [Boolean] :RWC
+  #
+  # @return YARD::Tags::Tag
   def format_gobject_properties(tag)
     text = tag.text
 
@@ -46,12 +69,28 @@ module YARD::Templates::Helpers::HtmlHelper
     properties = []
 
     unformatted_properties.each do |prop|
-      p = {:name => nil, :type => nil, :description => nil}
-      prop_regex = prop.match(/\A([\w\-]+) \[([\w\S ]+)\] *(.*)\z/)
+      p = {:name => nil, :type => nil, :access => nil, :description => nil}
+      prop_regex = prop.match(/\A([\w\-]+) \[([\w\S ]+)\] \:([RWC]+) *(.*)\z/)
 
       unless prop_regex.nil?
-        p[:name], p[:type], p[:description] = prop_regex.captures
+        p[:name], p[:type], p[:access], p[:description] =
+          prop_regex.captures
         p[:type] = p[:type].split /,\ */
+
+        access_split = p[:access].split ''
+        p[:access] = {:read => false, :write => false, :construct => false}
+
+        access_split.each do |a|
+          if a == 'R'
+            p[:access][:read] = true
+          elsif a == 'W'
+            p[:access][:write] = true
+          elsif a == 'C'
+            p[:access][:construct] = true
+          else
+            warn 'Only R, W, or C can be used as access permisions on a GObject Property.'
+          end
+        end
       end
 
       properties << p
@@ -59,5 +98,25 @@ module YARD::Templates::Helpers::HtmlHelper
 
     return properties
   end
+
+  # Formats the +:access+ key from a GObject Property.
+  #
+  # @see YARD::Templates::Helpers::HtmlHelper#format_gobject_properties
+  #
+  # @return [String] A string formatted as 'Read / Write / Construct'
+  def format_gobject_property_access(prop, separator=' / ')
+    access = prop[:access]
+
+    order = [:read, :write, :construct]
+    out = []
+
+    order.each do |o|
+      if access[o]
+        out << o.to_s.capitalize
+      end
+    end
+
+    out.join(separator)
+  end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: yard-gobject
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Stojan Dimitrovski