Module: Lazydoc::Attributes

Defined in:
lib/lazydoc/attributes.rb

Overview

Attributes adds methods to declare class-level accessors for constant attributes associated with the class.

# ConstName::key value
class ConstName
  extend Lazydoc::Attributes
  lazy_attr :key
end

ConstName::key.subject                 # => 'value'

Lazy attributes are inherited, but can be overridden.

class SubclassA < ConstName; end
SubclassA::key.subject                 # => 'value'

# SubclassB::key overridden value
class SubclassB < ConstName; end
SubclassB::key.subject                 # => 'overridden value'

You can use Attributes to register methods on modules, but currently the inheritance is a bit wonky; the accessors are methods on the extended class/module and so standard module inclusion will not pass them on. To work around you need to extend and redefine the accessors. Note, however, that methods do not need to be re-registered.

module A
  extend Lazydoc::Attributes
  lazy_attr(:one, :method_one)
  lazy_register(:method_one)

  # documentation for method one
  def method_one; end
end

class B
  include A
  extend Lazydoc::Attributes
  lazy_attr(:one, :method_one)
end

class C < B
  # overriding documentation for method one
  def method_one; end
end

A::one.comment    # => "documentation for method one"
B::one.comment    # => "documentation for method one"
C::one.comment    # => "overriding documentation for method one"

Keys and Register

Constant attributes parsed from a source file will ALWAYS be stored in const_attrs using a string (since the ‘ConstName::key’ syntax always results in a string key). A lazy_attr is basically shorthand for either of these statements:

ConstName.const_attrs['key'].subject            # => 'value'
Lazydoc::Document['ConstName']['key'].subject   # => 'value'

By default a lazy_attr maps to the constant attribute with the same name as the accessor, but this can be overridden by specifying the string key for another attribute.

class ConstName
  lazy_attr :alt, 'key'
end

ConstName::alt.subject                     # => 'value'
ConstName.const_attrs['alt']               # => nil

Comments specified by non-string keys may also be stored in const_attrs; these will not conflict with constant attributes parsed from a source file. For instance you could manually register a comment to a symbol key using lazy_register:

class Sample
  extend Lazydoc::Attributes

  lazy_register(:method_one)

  # this is the method one comment
  def method_one
  end
end

Sample.const_attrs[:method_one].comment    # => "this is the method one comment"

Manually-registered comments may then be paired with a lazy_attr. As before the key for the comment is provided in the definition.

class Paired
  extend Lazydoc::Attributes

  lazy_attr(:one, :method_one)
  lazy_register(:method_one)

  # this is the method one comment
  def method_one
  end
end

Paired::one.comment   # => "this is the method one comment"

Troubleshooting

Under most circumstances Attributes will register all the necessary files to make constant attributes available. These include:

  • the file where the class is extended

  • the file where a subclass inherits from an extended class

  • files that declare a lazy_attr

Be sure to call register_lazydoc in files that are not covered by one of these cases but nonetheless contain constant attributes that should be available to a lazy_attr.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#lazydocs ⇒ Object (readonly)

Returns the documents registered to the extending class.

By default lazydocs contains a Document for the file where Attributes extends the class, or where a subclass first inherits from an extended class (if you include Attributes, you must set lazydocs manually).

Additional documents may be added by calling register_lazydoc.



142
143
144
 
# File 'lib/lazydoc/attributes.rb', line 142

def lazydocs
  @lazydocs
end

Class Method Details

.extended(base) ⇒ Object

Sets source_file as the file where Attributes first extends the class.



122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/lazydoc/attributes.rb', line 122

def self.extended(base)
  caller[1] =~ CALLER_REGEXP
  unless base.instance_variable_defined?(:@lazydocs)
    base.instance_variable_set(:@lazydocs, [Lazydoc[$1]])
  end
  
  unless base.instance_variable_defined?(:@lazy_registry)
    base.instance_variable_set(:@lazy_registry, {})
  end
  
  super
end

Instance Method Details

#const_attrs ⇒ Object

Returns the constant attributes resolved for the extended class.



160
161
162
 
# File 'lib/lazydoc/attributes.rb', line 160

def const_attrs
  Document[to_s]
end

#registered_methods(as_registry = false) ⇒ Object

Returns an array of the methods whose documentation will be automatically registered by Attributes. Set as_registry to true to return a hash of of (method_name, [comment_class, caller_index]) pairs where the registration arguments are the hash values.



148
149
150
151
152
153
154
155
156
157
 
# File 'lib/lazydoc/attributes.rb', line 148

def registered_methods(as_registry=false)
  methods = {}
  ancestors.reverse.each do |ancestor|
    if ancestor.kind_of?(Attributes)
      methods.merge!(ancestor.lazy_registry)
    end
  end
  
  as_registry ? methods : methods.keys
end