Forum: Ruby on Rails [ANN] ColumnComments Plugin

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Duane J. (Guest)
on 2006-04-27 23:43
(Received via mailing list)
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/
Jodi S. (Guest)
on 2006-04-28 00:03
(Received via mailing list)
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
Duane J. (Guest)
on 2006-04-28 02:24
(Received via mailing list)
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 ;)
Jodi S. (Guest)
on 2006-04-28 17:53
(Received via mailing list)
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
Benjamin C. (Guest)
on 2006-04-28 18:02
(Received via mailing list)
Posted at http://agilewebdevelopment.com/plugins/show/105. :)
--
Benjamin C.
http://www.tesly.com/ -- Collaborative test case management
http://www.agilewebdevelopment.com/ -- Resources for the Rails community
Duane J. (Guest)
on 2006-04-28 18:17
(Received via mailing list)
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/
This topic is locked and can not be replied to.