Code objects are Ruby objects that describe the code being documented. For instance, all classes, modules, methods, etc. are all extracted from the Ruby source as code objects. All of these code objects extend from theclass, which provides basic attributes like source location, source code, name and path.
Code objects are divided into two basic types.
NamespaceObject). These objects
act like tree structures, maintaining a list of all of their direct children. All non
namespace objects are simply subclasses of the Base class. The
is a special kind of
NamespaceObject which refers to the top level namespace in Ruby.
Methods that accept a namespace object as a parameter should also accept the symbol
:root as a shortcut for the root object.
The following is an overview of the classes within the
Unique Path Representation
All CodeObjects are uniquely defined by their implementation of. This path is used to locate or store a code object in the . It is therefore essential that any Base subclass return a unique String value for #path so that the object may co-exist with other objects in the Registry.
In practice, a path is simply the conventional Ruby representation of a class, module, constant, class variable or method. For example, the following objects would have the following respective paths:
- Instance method
- Class method
- Class variable
CodeObjects classes are coupled with theclass which keeps track of all instantiated code objects. This is an explicit design choice to allow objects to be fetched, cached, imported and exported from a centralized location. As mentioned above, this coupling is a result of the fact that each object is uniquely identified by its path, which is used to implement lookups. You can read more about the registry in the class.
Code objects are instantiated using an identity-map like implementation that guarantees only one unique Ruby object exists for an object described by a specific path. This allows developers to create a code object without checking if it already exists in the. The following example will only create one object:
id = ClassObject.new(:root, "MyClass").object_id #=> 13352 ClassObject.new(:root, "MyClass").object_id #=> 13352
In addition to providing access to existing objects, a
Proxy and #type of
P(:InvalidObject).type == :proxy #=> true P(:InvalidObject).is_a?(Proxy) #=> true
Adding Data to Code Objects
Code objects act as hash-like structures that allow any arbitrary value to be set. This allows easy extending of existing objects without creating custom subclasses. For instance, to add a timestamp to a method object (when it was modified, maybe), it is possible to simply do:
object = MethodObject.new(:root, "my_method") object[:modified_at] = Time.now
This value can now be retrieved on this object both by the hash
 syntax as
well as like any other method:
object.modified_at #=> 2009-06-03 20:08:46 -0400
Creating a Custom CodeObject
It should first be mentioned that creating a custom code object should not be necessary in most cases, except when functionality that cannot be represented by classical Ruby objects is added. A good example might be a test class, which although is technically a Ruby class, has a significantly different purpose in documentation and needs a different set of metadata, as well as its own representation in documentation.
def path "__FooPrefix" + sep + super end
Note that if our FooObject is a
NamespaceObject, meaning if it can have child
FooObjects defined inside of it, you may need to verify that the prefix is only