Community
Participate
Working Groups
This has been bugging me for a while and since Helios is now mostly behind us, I figured I'd take a minute and open a bug. The first parameter for NLS.initializeMessages() is called 'bundleName' and the javadoc description for it is "fully qualified path of the class name". There's an obvious mismatch between the param name and the description. A bundle and a class are two completely different concepts. Which is right? The param name or the javadoc? Is it the class name? The second parameter is the Class file object. The NLS implementation can get the fully qualified path from that object, so why ask the caller for it? That can't be it. OK, so the param name must be right; it's a bundle. But, that alone is also confusing. The term 'bundle' is overloaded in the Eclipse world. In many (most) cases, the term 'bundle' refers to an OSGi bundle. So, the javadoc should be explicit that we're talking about a _Java resource bundle_. Now, I've been playing dumb here. I know exactly what the parameter represents...but that's only because when I first used the method, I looked at how clients call it and deduced the meaning from them. Developers new to that method shouldn't have to rely on that. That's my point here.
agreed. I will work on fixing this.
Created attachment 173820 [details] javadoc patch Here is an attempt to improve the javadoc for initializeMessages. I changed the bundleName param name to baseName. I also documented that the class loader of the specified class is used to load the message properties resource. I hope this makes things a bit more clear.
I released this to head. Feel free to reopen if you have suggestions for additional improvements.
(In reply to comment #2) > Created an attachment (id=173820) [details] > javadoc patch > > Here is an attempt to improve the javadoc for initializeMessages. I changed > the bundleName param name to baseName. I also documented that the class loader > of the specified class is used to load the message properties resource. I hope > this makes things a bit more clear. Tons clearer. Thanks. BTW, I think there might be a word missing in the second sentence, specifically the section starting with "including the package...". Either "package *where*" or "located *in*" would fix the grammar, I believe. Regardless, the message is clear and this is a huge improvement.
(In reply to comment #4) > (In reply to comment #2) > > Created an attachment (id=173820) [details] [details] > > javadoc patch > > > > Here is an attempt to improve the javadoc for initializeMessages. I changed > > the bundleName param name to baseName. I also documented that the class loader > > of the specified class is used to load the message properties resource. I hope > > this makes things a bit more clear. > > Tons clearer. Thanks. BTW, I think there might be a word missing in the second > sentence, specifically the section starting with "including the package...". > Either "package *where*" or "located *in*" would fix the grammar, I believe. > > Regardless, the message is clear and this is a huge improvement. I released an update to add the missing word *where*. Thanks for the review.
