[ANN] ColumnComments Plugin

Rails
1

Hereâ??s a small plugin that may be useful for documenting your
database. Based on Dave T.â??s AnnotateModels plugin, this plugin
goes one step further and allows you to store comments on each column
in the database (MySQL only).

Full write-up at: http://blog.inquirylabs.com/2006/04/27/
columncomments-rails-plugin

Subversion at: svn://syncid.textdriven.com/svn/opensource/
column_comments/trunk

Duane J.
(canadaduane)
http://blog.inquirylabs.com/

2

Great Stuff Duane. This and the recent MARC(?) textmate plugin are
much appreciated.

Question: What would it take to have annotations with the Model?

I have an client that utilizes Model attributes as fields in a mail
merge. The annotations would be great for me within the Model for end
user documentation.

Cheers,
(Canada)Jodi

3

On Apr 27, 2006, at 1:59 PM, Jodi S. wrote:

Great Stuff Duane. This and the recent MARC(?) textmate plugin are
much appreciated.

Thanks, Jodi. Glad you like them. (I’m rather fond of the MASC
feature right now. Discovering new uses for it all the time.)

Question: What would it take to have annotations with the Model?

I have an client that utilizes Model attributes as fields in a mail
merge. The annotations would be great for me within the Model for
end user documentation.

I’m not quite sure I understand your question. Currently, the
annotations go right in to the comment section of the model. The
“rake doc:reapp” task can then be called to automatically create
documentation from that comment section (assuming there are no other
comment blocks between the auto-generated block and the class
itself). Is this what you’re after?

Duane

Cheers,
(Canada)Jodi

Haha! Good to have you on board :wink:

4

On 27-Apr-06, at 6:22 PM, Duane J. wrote:

I’m not quite sure I understand your question. Currently, the
annotations go right in to the comment section of the model. The
“rake doc:reapp” task can then be called to automatically create
documentation from that comment section (assuming there are no
other comment blocks between the auto-generated block and the class
itself). Is this what you’re after?

Duane

Thanx Duane - (just waking up, rubbing sleep out of my eyes, and
trying to summarize)

I have some ‘decorator’ methods that pretty up the output from the
database (think phone numbers, postal codes, etc). Some times these
methods bring together data from multiple fields to build a visually
pleasing output such as name (honoration + firstname + initial +
lastname). These fields are only present in the Model.

As the ColumnComments plugin works on the database column (as it
should!), I guess you’re saying I should just add comments to the
ruby source code that rdoc picks up?

I’d like to provide my users with a way to query the database column

  • public model attributes, and CRUD the comments. I can think of ways
    to do this with a data dictionary in the database, but your
    announcement got me thinking their might be a better way.

Is that clear? (hoping I’m awake enough by now)

Cheers,
Jodi

5

Posted at http://agilewebdevelopment.com/plugins/show/105. :slight_smile:

Benjamin C.
http://www.tesly.com/ – Collaborative test case management
http://www.agilewebdevelopment.com/ – Resources for the Rails community

6

On Apr 28, 2006, at 7:52 AM, Jodi S. wrote:

Duane
As the ColumnComments plugin works on the database column (as it
should!), I guess you’re saying I should just add comments to the
ruby source code that rdoc picks up?

Yes, you would have to add comments inline with your code in this
case. There’s no facility (that I know of) for “pseudo-columns” in
the MySQL database that would provide a place to document columns
that don’t really exist in the DB.

I’d like to provide my users with a way to query the database
column + public model attributes, and CRUD the comments. I can
think of ways to do this with a data dictionary in the database,
but your announcement got me thinking their might be a better way.

That sounds pretty cool. As for implementation, I would think you’d
have to do a little of both–update the comments on the real database
fields, and update the ruby comments in your model code–to get what
you’re after. It might be easier in the end to create a “comments”
table for this to normalize how you do commenting in your system.
Unless DRY is important to you, in which case you may want to re-use
all the inline ruby comments.

Good luck!

Duane J.
(canadaduane)
http://blog.inquirylabs.com/