[GenerateToString] Javadoc on toString?

is there a way to template the javadoc that goes
with the generated toString() method? I'm not a big
fan of undocumented public methods and I like to be
consistent even with toString() methods.

Thanks,

Vince.


14 comments
Comment actions Permalink

The Javadoc tool inserts javadoc from Object.toString's docs into your toString methods, as long as you pass the right JDK source path. Personally I don't document toString because there's nothing to say beyond what Object.toString's docs say.

0
Comment actions Permalink

The javadoc from Object.toString() is both too general and too specific for
my needs. I might also want to capture in the javadoc that the toString
method is automatically generated and maintained.

Vince.


0
Comment actions Permalink

I wonder if the velocity template could be used to add such javadocs.

// let template generate here too
public String toString{}{
// currently generated by template
}

For that matter, could GenerateToString be generalized to generate methods (and maybe their javadocs) for methods other than toString, such as constructors, compareTo, equals, hashcode, myOwnFrequentlyWrittenMethod(), etc?

0
Comment actions Permalink

I have included this feature in my idea list (README.TXT) in the .jar archive of the plugin.

Since the community (you) are requesting a feature to set the javadoc comments from within the template code I would work on a solution for this in the next release. I should have time this weekend.

Idea for Velocity syntax:
#javadoc("Outputs the fields from this object")

And maybe I would add a edittext in the UI to set a standard javadoc text.

Any comments? Before I hack something together?


/Claus

0
Comment actions Permalink

How about Brian's idea of having the template include
the method signature also?

=== template-begins ====
/**

  • some comments with some templated stuff

*/
public String toString() {
// more stuff
}
=== template-ends ====

That would be handy.

Thanks,

Vince.


0
Comment actions Permalink

Hi

Actually yes this loooks more intuitive to have the method signature and the javadoc comments on top. If you do not want the javadoc you just delete it.

However there would be some restriction to keep the method signature in the text consistent as the plugin should parse the text to know:
- what is javadoc
- what is method signature
- what is javacode

But todays reg.exp. are good at parsing texts. To honor different code styles:

public String toString() {
...
}

public String toString()
{
...
}

This would maybe break exisiting templates so I would start working on this in a future release, as v2.13 is nearly done.

/Claus

0
Comment actions Permalink

For that matter, could GenerateToString be
generalized to generate methods (and maybe their
javadocs) for methods other than toString, such as
constructors, compareTo, equals, hashcode,
myOwnFrequentlyWrittenMethod(), etc?

I have considered that also.

But is there really a demand for a template based solution to create other methods than toString()?

Today you could also use IDEAS existing live templates to create method skeletons.

I was considering having a quick menu with your selections of templates avail - something like alt + ins but listing the templates you have choosed to be listed here. And if these templates are capable of generating toString(), compareTo(), toXML() and whatever. However it would require the template information to be more strong with informations about methods, inserting javadoc comments, automatic adding implementions etc. But many of these features are more or less already in the velocity context.

This is something I would like to aim for improving the plugin to be able to generate other methods than toString() by allowing to specify the method signature in the template code.


/Claus

0
Comment actions Permalink

That sounds like a lot of work.

What about having another small template just for the
javadoc? You would keep the configuration the same
and you would add another template area for the
"Method javadoc" right next to the "Method body" one.

Just another thought :)

Vince.


0
Comment actions Permalink

But is there really a demand for a template based
solution to create other methods than toString()?


IMHO, absolutely.

Today you could also use IDEAS existing live
templates to create method skeletons.


The problem with live templates is one has a very limited selection of variables to use in writing the template.


I was considering having a quick menu with your
selections of templates avail - something like alt +
ins but listing the templates you have choosed to be
listed here. And if these templates are capable of
generating toString(), compareTo(), toXML() and
whatever. However it would require the template
information to be more strong with informations about
methods, inserting javadoc comments, automatic adding
implementions etc. But many of these features are
more or less already in the velocity context.

This is something I would like to aim for improving
the plugin to be able to generate other methods than
toString() by allowing to specify the method
signature in the template code.


IMO this could potentially be tremendous. I think GenerateToString could be the starting point for "Live Templates on Steriods".

0
Comment actions Permalink

An extra textarea might clutter the UI. However this would be the easy solution as the two text areas are seperated and no parsing are needed.

Maybe somethhing like:

Enable javadoc editor

Javadoc
-


/**

  • Type your javadoc here!!!

*/

Velocity Template
-


Here goes normal templates


But I would try both options to see what works, however the solution to keep it in one template is the one I like the most to keep it similar to normal javacode.

/Claus

0
Comment actions Permalink

Just as info

I got an experimental version up and running with a solution to add javadoc to the toString method.

I need to integrate in into the settings UI.

However my sparetime have been pretty occupied lately but the comming weekdays should have time in the evenings for finishing this feature and release a version.

/Claus

0
Comment actions Permalink

Good news :)

Something to think about (with a lower priority than you current requests
though) is what to do when there is already a toString() method with a
javadoc. The options could be
- Replace body and javadoc
- Replace body only, keep javadoc
- duplicate
- cancel

Thanks,

Vince.


0
Comment actions Permalink

Something to think about (with a lower priority than
you current requests
though) is what to do when there is already a
toString() method with a
javadoc. The options could be
- Replace body and javadoc
- Replace body only, keep javadoc
- duplicate
- cancel


Yeah that is also a problem. I think the first solution would be to keep the existing javadoc to not overwrite anything you have typed.

An option later with a dialog, resolution policy could be added to the plugin.

I think if you for some reason have added the javadoc yourself this javadoc comment is specific/important and should be kept as such.

/Claus

PS: I integrated the solution where you add the javadoc directly in the veloctiy template. However IDEA throws a strange line break error if the template file is saved, then the line breaks in the javadoc comments causes this exception. If you just manually type the javadoc comment there is no error. I will look into it now (also upgrading to build 2013)

0
Comment actions Permalink

v2.14 is just released with this feature now.

/Claus

0

Please sign in to leave a comment.