|
Please offer this feature soon. I have also a lot of tables and columns to be documented.
Is there an roadmap, when this feature will be available? If you're interested in contributing, let me know.
Yes I am interested in contributing.
How will we go on? Great!
Start downloading the code svn http://anonsvn.jboss.org/repos/hibernate/core/branches/Branch_3_2/ core svn http://anonsvn.jboss.org/repos/hibernate/annotations/trunk/ annotations in code run ant prepare-dir-up then the code is in annotations Specifically, you are looking for AnnotationBinder / PropertyBinder / SimpleValueBinder I think What I imagine is a @ColumnOrFormula annotation @ColumnOrFormula(column=@j.p.Column, formula=@Formula, @o.h.a.Column) @o.h.a.Column is a new annotation that would host thew comment Let's move the discussions to the development mailing list hibernate-dev@lists.jboss.org (needs registration to post) Meanwhile, I have a work-around: generate the HTML documentation and then use XSLT to add the column descriptions.
First, I define the comments in an XML file, where the id attributes are table names and column names. <?xml version="1.0" encoding="UTF-8"?> <column-descriptions> <table id="customers"> <column id="customer_id">Primary key</column> <!-- more columns --> </table> <!-- more tables --> </column-descriptions> Then I transform each generated table_name.html file with the following XSL 2.0 stylesheet. XSL version 2 is required, to have multiple source documents. <?xml version="1.0" encoding="UTF-8"?> <xsl:transform version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xpath-default-namespace="http://www.w3.org/1999/xhtml"> <xsl:output method="xhtml" doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" /> <!-- Identity transformation. --> <xsl:template match="node()"> <xsl:copy> <xsl:copy-of select="@*" /> <xsl:apply-templates /> </xsl:copy> </xsl:template> <!-- Column detail section: copy the heading, then output a paragraph containing the column description from column-descriptions.xml. --> <xsl:template match="h3"> <xsl:copy-of select="."/> <xsl:variable name="table" select="substring(/html/body/h2[1], 7)"/> <xsl:variable name="column" select="substring(@id , 15)"/> <p><xsl:value-of select="document('column-descriptions.xml')//*[@id=$table]/*[@id=$column]"/></p> </xsl:template> </xsl:transform> The easiest way to run this is to use Saxon-B 9.0 (http://saxon.sourceforge.net/) and the following Ant task. <xslt style="source/column-descriptions.xsl" basedir="build/hbm2doc/tables" destdir="build/documentation" force="yes"> <classpath location="lib/saxonb9-0-0-2j/saxon9.jar"/> <include name="**/*.html" /> </xslt> Also, while I am at it, I added templates to the XSL stylesheet to replace the HTML LINK element so I can point to my own stylesheet. Hi all,
after reading the documentation and the API-doc, it didn't seem that this issue has been fixed (I'm new to hibernate, so I might be wrong). Anyway, I downloaded hibernate-annotations-3.3.0.ga and worked in the "@Comment"-annotation for Tables and Properties. It's not been widely testet. But it seems to be working just fine. The attached file contains the svn-diff. I hope that this works with patch. If not, please tell me what to do to create a correct patch-file. Just tell me, if that patch is helpful for you and if everything is implemented ok. As I said, it needs more that @Comment
" What I imagine is a @ColumnOrFormula annotation @ColumnOrFormula(column=@j.p.Column, formula=@Formula, @o.h.a.Column) @o.h.a.Column is a new annotation that would host thew comment " Some properties are multi column Ok,
so now I get want you want. I'm not quite understanding what the problem is with the @Comment annoation. But if you could show me an example, where @Column leads to a problem, I might get it. And if I get it, I might implement it, the way you suggested. It's just that I think, that @Comment is far more readable, cause comments tend be be quite long and would otherwise distract from the functionally important properties. Just help me understandig your prob. Following Emmanuel's ideas, I was wondering why not to try this approach:
@ColumnOrFormula(column=@j.p.Column, formula=@Formula, comment="...") I think @ColumnOrFormula is an abstraction that fullfills the requirements of an hypothtical annotation @o.h.a.Column. With just one annotation @ColumnOrFormula, we could comment not only columns but formulas too. I believe we'll need an annotation to group ColumnOrFormula's: @ColumnsAndFormulas(columnsAndformulas={@ColumnOrFormula(column=...), @ColumnOrFormula(@formula=)...}) What do you think? PS: I didn't find any unit test for table comments inside Hibernate Annotations project. I would like to know if it's worth to create unit tests for new annotations (specially for column comments)? I am interested in contributing as I need this feature implemented as soon as possible. sorry for the delay. A formula cannot have a comment.
As I said you can have multiple columns per property and then several comments on the same property, hence @ ColumnOrFormula to host it. BTW I am not against the ability to use @Comment straight on the property for simple cases, but the complete feature needs to be implemented as well and that implies the @ColumnOrFormula thing. It would be nice to have a test case but this can be quite hard. There might be an example in the Hibernate Core test suite. I think I now ran into some similar problem with embedded classes. In this case you also have one property and multiple columns.
Though the @Column Tag works fine within the embedded class, it leads to a problem: Generally the comments in the embedded class are correct, but they are missing the point to describe in what way the embedded class might be used. As an example you could think of a "person" which has two address-properties "invoiceAddress" and "deliveryAddress" both represented by an embedded class "Address". In both cases comment annotations would be correct in a way, that the street is the name of the street, and that the zip-code denotes the zip-code of the city or area. But the comments for delivery and invoice address would be exactly the same. Not ideal. Im thinking of a way to achieve this with CommentPrefix or CommentSuffix annotation, but that's only a rough Idea. I will give ColumnOrFormula a thought, but it will not fix the problem mentioned. Because in the end the commented embedded class is correctly commented. It only misses additional information on the way it is used. I will put some more thought into that. Anyway, I think it would be a great improvement if at least @comment would be available. Something to keep in mind - the Infobright MySQL storage engine looks for a column comment of 'lookup' to trigger storing a column as lookup values rather than raw values. Whatever implementation is done for comments in annotations should try to play nice with this (admittedly hackish) convention:
http://www.infobright.org/wiki/How_and_When_to_use_Lookups/ |
||||||||||||||||||||||||||||||||||||||||||||||
 |
|
Improvement
Open
Major
Support @Comment or column attribute on @Table and @Column
There is no vehicle yet for column comments