Need of a self explanatory method like toString(): Your Opinion?

Question

Hi All,
If including a method like showHelp() is recommended as
java programming standard like incorporating toString() in
a class, it will serve as an online help mechanism for
developers using the class. It will be helpful reference
when the source code or API documentation is not available.
Also it will be a nice mechanism for the coder to give
usage information of his class to a newbie or intermediate java programmer.
Example:
public class MyClass {
public int width;
public MyClass() {
public String toString() {
return "Class:MyClass, width:"+width;
public String showHelp(){
String help;
help = "This class is intended to use for.. \n\n";
help += "Typical Usage is... \n\n";
help += "Sample code as followed...\n\n Thank you.";
return help;
}This is what Sun's reply when I submit the feature.
"If you feel this should be implemented and the need is justified,
please start a topic in the JDC forum to see if there is support, and
email me the link. Thanks."
Please share your views regarding this feature.
Thanks.
-bathra

Answer 1

My question is how would this build over Javadoc standards? With the showHelp() method available, wouldn't this be useful only for the programmer? What about running Javadoc on the class and reading the html produced by it? That's what it's there for.
http://java.sun.com/j2se/1.4/docs/api/index.html
If a closed source class file does not have well written thorough documentation, what good will the showHelp() provide? If the documentation isn't available, the question would be why should the class file even be used if you won't have the documentation to be able to use it properly. If the class file is a purchased 3rd party component, that group is responsible for providing good documentation.
This would dramatically increase the size of the compiled Java Bytecode as most comments I've seen are more than tripple than the source of a .java file. Including the comments as an output method could be overkill. My personal opinion is to follow the Javadoc standard and include the html output. Well written tight code is mainly what I'm after.