I'm using YARD on my Rails project and was wondering how I would go about documenting inherited/runtime methods on a Rails model? For instance documenting the existence of a first_name attribute on a User model.
You can't do that, IMHO.
The trouble is that those methods don't really "exist"; They are "created on the fly" via method_missing hooks, the first time they are invoked, on runtime.
Other documentation generation systems have ways to declare "implicit" methods. For example NaturalDocs has a function keyword that allows you to create functions that only exist on the comments. I'm not familiar enough with YARD, but it seems it doesn't have a similar functionality.
Good luck!
Related
Is there a reason why ActiveRecord's bang methods are public, but not documented nor mentioned anywhere?
For example, where!, order!, limit! and others are all public and used by their non-bang counterparts.
I understand that they change the query object instead of its clone (and caution is necessary), but so do other bang methods, which are usually very well-documented.
They want to keep the API to be immutable, see the comments on this commit:
https://github.com/rails/rails/commit/8c2c60511beaad05a218e73c4918ab89fb1804f0
And as for all undocumented methods (with # :nodoc:), they are part of the private API.
You should not use them as they could be removed without a warning.
hth
Disclaimer: I'm not a RoR contributor, so if there is some RoR specific reason to it, I don't know.
As you said, they are wrapped by their non-bang counterparts. The where method for example checks if the method has the correct number of arguments and applies a the current scope to it. Moreover it provides the polymorphic behavior outlined in the documentation.
Source: https://github.com/rails/rails/blob/4c0d6680ee011b822e6beaa1ee84f835e89550a1/activerecord/lib/active_record/relation/query_methods.rb#L550
My impression is that they are this way for abstraction reasons. The bang methods implement a lower level of functionality, while the non-bang methods provide a more user-friendly interface. As to why they are not documented but are public, I think the library authors wanted to provide the option to use them if you really know what you're doing.
Absolute beginner with ruby and with rails. My first full blown project will interface with an existing system through a REST api.
So it doesn't employ the normal ActiveRecord model and I was hoping for some examples of projects that replace the normal use of models with API calls. The entire CRUD set will require the app to make the corresponding API calls. I'd like to do this the right way, just don't know what that looks like yet.
Thanks! :)
Helpful links for googlers:
http://yetimedia.tumblr.com/post/35233051627/activeresource-is-dead-long-live-activeresource
https://github.com/rails/activeresource
I don't know of any projects that are open source that do this, but I'd recommend looking into Active Resource. It was part of Rails through 3.2, but has been moved to a separate repo for Rails 4. The idea is that it lets you replace database persistance with RESTful APIs, which sounds like exactly what you're trying to do. There is some documentation here which should give you enough info to get off the ground. There's also a pretty old Railscast on it, but I'm sure the concepts haven't really changed that much.
Here's an example from the docs that shows how to setup your "model":
class Person < ActiveResource::Base
self.site = "http://api.people.com:3000"
end
I'd suggest leveraging ActiveModel so your models aren't 'AR' backed, i.e. no persistance via AR. You'll handle CRUD accordingly in your controllers and craft your own 'business logic' that you can tuck into your ActiveModel.
I am using Ruby on Rails 3.0.7 and I have multiple resources that almost have the same behavior. That is, those almost have same model, controller and view codes and same database table columns definition.
So I would like to find a way to DRY those resources. I already implemented modules and mixins for those in order to share part of the code (as validation methods, callbacks, view files but not controller files that, anyway, have very similar code).
Now, how can I do to handle this common behavior? Should I use something that Ruby on Rails developers named as acts_as_something? What do you advice about?
I think you already did that, just name a method in your modules act_as_your_module_name and make sure your module extends from your Base Class, e.g. ActiveRecord::Base.extend act_as_your_module_name
http://www.cowboycoded.com/tag/acts_as/
I just started to document a rails application. I know this is actually done by rdoc, so I followed some rdoc guides regarding syntax and so on, but I got stuck when I tried to describe attributes of models, validations and the relationship between models, mostly because these things are part of ActiveRecord. So I wonder if there is some guide or a good practice regarding how to document a rails application or if there is something I'm missing?
I know that I could put all of this in the class description, but I wonder if there is a way more closely tied to the declaration itself (has_many, validates_presence_of, etc.) and what about the attributes?
I personally prefer YARD - http://yardoc.org , as it does a better job in documenting IMHO.
I don't know if there's a specific handler for Rails available, but it's quite easy to write one - http://yardoc.org/guides/extending-yard/writing-handlers.html
A good example might be the attribute handler - part of the yard gem:
lib/yard/handlers/ruby/attribute_handler.rb
Remember your tests are part of the documentation (for developers), particularly if you are using Cucumber where scenarios are easy to read. If you keep your methods very short and there is a test method with a descriptive name e.g. "should set the users name" I find I typically don't need comments on the method.
Validations or other parts of Rails I would not document. Part of being a Rails developer is understanding how these work, I think it is a fair assumption that another maintainer of your code reading it down the road will know validations, or other things built in to Rails. By that same logic, if you can use features of the framework or happy paths (not deviate much) with [documented] third party code, a lot of the documentation will be written for you.
In Rails, the closest I've seen to Django Signals are Observers. The problem with them is that they're restricted to triggering callbacks on hardcoded events related to a model's lifecycle.
Django signals can be created anywhere, triggered anywhere and handled anywhere. The model lifecycle callbacks are just regular signals that happen to come built-in and that are triggered by the ORM.
Does anyone know of a similarly general solution for Rails? It could be some generic Ruby library, not tied to Rails, which would be even better.
Edit: Observer is the closest thing, but it's not what I'm looking for. It's a one-to-many solution. Anyone can listen, but only the originating object can post. I'd like something where you declare a signal, and anyone can trigger it as well as handle it. Also, I don't like the fact that the Ruby Observer dictates that the handler have an #update method. I'd like to be able to pass any method reference with the appropriate signature.
I could use the Ruby Observer to implement my own such broker, but I'm trying to learn if someone already did it.
I think a closer equivalent than Rails' Observer is the standard Ruby Observable module. It lets you add a list of observers to an object and the object can then send notifications to the observers when it changes.
What about the 'wisper' gem? https://github.com/krisleech/wisper
Wisper is a Ruby library for decoupling and managing the dependencies
of your Ruby objects using Pub/Sub.
It is commonly used as an alternative to ActiveRecord callbacks and
Observers to reduce coupling between data and domain layers.
Perhaps acts_as_state machine will help. Most of this functionality has recently been baked into Rails edge.
I just implemented a gem with that. https://github.com/pkoch/django_signal/
Ruby gem 'watchable' is the most appropriate choice
https://github.com/jbarnette/watchable
It has a syntax that is very familiar to Django's (and other frameworks, like Qt and many others).