[Sculptor] Generate javadoc for attributes?

[amphoras]

Hi,

First of all, I'm really impressed with Sculptor!  I thought that I was going to have to write something similar and not nearly as powerful, and then I discovered this project.  So thanks for making my life easier.  :)

I do have a question though.  Is there any way to generate javadoc for the attributes in the domain object?  For example, I would like my class to declare attributes like this:

        /** Address Line 1. */
        private String addressLine1;
       
        /** Address Line 2. */
        private String addressLine2;
       
So I edited the "model.design" file like this:

        /** Address Line 1. */
        String addressLine1 nullable
       
        /** Address Line 2. */
        String addressLine2 nullable

However, the comments are ignored.  I also looked at the DomainObject.xpt template, but I cannot figure out how to get to the comments.  I'd like to be able to generate them because we have a Checkstyle rule that all attributes must be commented.  Plus, it's just nice for documentation purposes.  So how should I specify the comments?

Thanks!
--Polly

[Alberto de Arriba]

You must modify the "DEFINE attribute FOR Attribute" section in
DomainObject.xpt (lines 125-127).

There's another option. Edit your SpecialCases.xpt file, which should be
located in src/main/resources. You must add something like this:

«AROUND *::attribute FOR Attribute»
    /** «name» */
    «targetDef.proceed()»
«ENDAROUND»

> -----Mensaje original-----
> De: fornax-developer-bounces@... [mailto:fornax-
> developer-bounces@...] En nombre de amphoras
> Enviado el: miércoles, 25 de junio de 2008 0:14
> Para: fornax-developer@...
> Asunto: [Fornax-developer] [Sculptor] Generate javadoc for attributes?
>
>
> Hi,
>
> First of all, I'm really impressed with Sculptor!  I thought that I was
> going to have to write something similar and not nearly as powerful, and
> then I discovered this project.  So thanks for making my life easier.  :)
>
> I do have a question though.  Is there any way to generate javadoc for the
> attributes in the domain object?  For example, I would like my class to
> declare attributes like this:
>
> /** Address Line 1. */
> private String addressLine1;
>
> /** Address Line 2. */
> private String addressLine2;
>
> So I edited the "model.design" file like this:
>
> /** Address Line 1. */
> String addressLine1 nullable
>
> /** Address Line 2. */
> String addressLine2 nullable
>
> However, the comments are ignored.  I also looked at the DomainObject.xpt
> template, but I cannot figure out how to get to the comments.  I'd like to
> be able to generate them because we have a Checkstyle rule that all
> attributes must be commented.  Plus, it's just nice for documentation
> purposes.  So how should I specify the comments?
>
> Thanks!
> --Polly
> --

-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Fornax-developer mailing list
Fornax-developer@...
https://lists.sourceforge.net/lists/listinfo/fornax-developer

[amphoras]

Hi Alberto,

Thank you for the quick response.  Using «name» would only print out the name of the attribute in the javadoc, right?  I mean I know that would pass Checkstyle, and my example was simple like that, but what if I want the javadoc to actually be a descriptive paragraph?  Is the comment saved anywhere in the model?

Thanks!

--Polly

Alberto de Arriba wrote:

You must modify the "DEFINE attribute FOR Attribute" section in
DomainObject.xpt (lines 125-127).

There's another option. Edit your SpecialCases.xpt file, which should be
located in src/main/resources. You must add something like this:

«AROUND *::attribute FOR Attribute»
    /** «name» */
    «targetDef.proceed()»
«ENDAROUND»



> -----Mensaje original-----
> De: [e-mail] [mailto:fornax-
> [e-mail]] En nombre de amphoras
> Enviado el: miércoles, 25 de junio de 2008 0:14
> Para: [e-mail]
> Asunto: [Fornax-developer] [Sculptor] Generate javadoc for attributes?
>
>
> Hi,
>
> First of all, I'm really impressed with Sculptor!  I thought that I was
> going to have to write something similar and not nearly as powerful, and
> then I discovered this project.  So thanks for making my life easier.  :)
>
> I do have a question though.  Is there any way to generate javadoc for the
> attributes in the domain object?  For example, I would like my class to
> declare attributes like this:
>
> /** Address Line 1. */
> private String addressLine1;
>
> /** Address Line 2. */
> private String addressLine2;
>
> So I edited the "model.design" file like this:
>
> /** Address Line 1. */
> String addressLine1 nullable
>
> /** Address Line 2. */
> String addressLine2 nullable
>
> However, the comments are ignored.  I also looked at the DomainObject.xpt
> template, but I cannot figure out how to get to the comments.  I'd like to
> be able to generate them because we have a Checkstyle rule that all
> attributes must be commented.  Plus, it's just nice for documentation
> purposes.  So how should I specify the comments?
>
> Thanks!
> --Polly
> --


-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Fornax-developer mailing list
[e-mail]
https://lists.sourceforge.net/lists/listinfo/fornax-developer

[Patrik Nordwall]

Thanks for your positive feedback.

Documentation can be added to most elements in model.design using quoted string above it, like this:
"This class is responsible..."
Entity Planet {
  "The name of the planet..."
  String name
}

JavaDoc based on this documentation is generated. For attributes it is generated in the getter-methods, not at the private field declaration.

Is that ok for you?  

My opinion:
I would never use a checkstyle rule that complains about missing JavaDoc for private fields.
I wouldn't even use checkstyle rule that complains at the method level either. If you use good naming you don't need JavaDoc for most of the methods. If you make it mandatory it will only be trivial documentation to satisfy the rule, which will be a maintenance burden.

/Patrik

[amphoras]

Hi Patrik,

Great!  I am so glad to know that there is a way to document the model and have it be generated as javadoc.  This is good enough for me.  I can modify the template to get what I need.  And I agree that the Checkstyle rule is kind of a pain.  It's useful about half the time.  :)

Thanks!
--Polly

Patrik Nordwall wrote:

Thanks for your positive feedback.

Documentation can be added to most elements in model.design using quoted string above it, like this:
"This class is responsible..."
Entity Planet {
  "The name of the planet..."
  String name
}

JavaDoc based on this documentation is generated. For attributes it is generated in the getter-methods, not at the private field declaration.

Is that ok for you?  

My opinion:
I would never use a checkstyle rule that complains about missing JavaDoc for private fields.
I wouldn't even use checkstyle rule that complains at the method level either. If you use good naming you don't need JavaDoc for most of the methods. If you make it mandatory it will only be trivial documentation to satisfy the rule, which will be a maintenance burden.

/Patrik