Annotations / Documentation on Entities / Active Record Models

[johnoponno]

I'm new to Ruby and Ruby on Rails and also new at the company where I work. As part of my on-boarding process I am trying to use Rails ERD as a tool for learning and documenting database models in our various projects.

I think it would be very useful to be able to attach some sort of annotation / documentation to these diagrams, for example a short blurb about what each Active Record Model is meant to represent in domain specific / biz terms.

Since all of this is generated reflectively I'm thinking that the best thing would be to have this documentation in the actual Ruby file for each given Active Record Model class. I'm new to Ruby / Rails but understand that Ruby is very flexible / mutable so I'm thinking that there should be some way to be able to attach information to a class.

From there changes could be made to Rails ERB to recognize these kinds of annotations and generate more stuff in the diagrams. I'm visualizing little Post-It notes with a different shape than the Active Record Models which are attached to same.

Of course such a scheme will suffer from the same problems that comments in code do when the code diverges from what the comments say, but that is of course in the very nature of such documentation.

The bottom line is that Rails ERD is super-useful already in that it handles complete diagram generation based on the source of truth (the code), which is a pre-requisite for the diagrams themselves to be up to date at all. With some kind of annotation feature I think it would be even more useful.

I would appreciate any feedback on the feasibility of this!

[kerrizor]

I could see this being pretty useful, actually, although it might make it a bit unwieldy and large in size.

We could add support for RDOC (or whatever flavor of documentation commenting you prefer) and just pull that in, but it'd require a separate pass through the code with an RDOC engine to extract; def something we'd need a flag for.

One other possibility would be to show the source code location/file name of where the class is defined. For each class:

file_locations = SomeClass.instance_methods(false).map { |m| 
  YourClass.instance_method(m).source_location.first
}.uniq

Hmmm.. from just that list of files we might be able to extract the RDOC (I haven't worked with an RDOC parser before, I'm hand waving here..) instead of having to parse the entire application (which can be slow)

[johnoponno]

Yes I assume things will get huge. I'm already scrolling around a gigantic .svg on one of our projects, so one could argue that things can get super dense and hard to understand, but I really value the overview of the 2d diagrams as opposed to just trying to read db/structure.sql or something similar.

Your suggestion of going from Active Record Models to source of same to just parsing those files sounds like a very reasonable optimization. I haven't looked into how ERD specifically finds all the Active Record Models, but I'm assuming something along the lines of scanning all the files.

On the other hand I see this mostly being used as an offline / on-demand thing for whenever someone (new developers mostly) needs to get a map over the the structure and look at the corresponding notes, so it doesn't need to be super fast.

[thbar]

Is there currently a way (even a hack) to pick what's atop the class declaration (comment) and inject it under the model name?

[sfcgeorge]

Rails now supports database level comments which are wonderful. In migrations you can use:

change_column_comment(:posts, :state, from: "", to: "Whether the post is live/archived/draft etc")
change_table_comment(:posts, from: "Blog posts", to: "Articles for the public blog")

It would be great to have a config option to include these.