Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 316378

Summary:

NLS.initializeMessages() parameter description confusing

Product:

[Eclipse Project] Equinox

Reporter:

John Cortell <john.cortell>

Component:

Framework

Assignee:

Thomas Watson <tjwatson>

Status:

RESOLVED FIXED

QA Contact:

Severity:

normal

Priority:

CC:

tjwatson

Version:

3.6

Target Milestone:

3.7 M1

Hardware:

OS:

Windows XP

Whiteboard:

Attachments:

Description	Flags
javadoc patch	none

Description John Cortell

2010-06-09 16:26:38 EDT

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.

Comment 1 Thomas Watson

2010-06-09 16:35:28 EDT

agreed.  I will work on fixing this.

Comment 2 Thomas Watson

2010-07-08 17:21:55 EDT

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.

Comment 3 Thomas Watson

2010-07-08 17:24:00 EDT

I released this to head.  Feel free to reopen if you have suggestions for additional improvements.

Comment 4 John Cortell

2010-07-08 17:34:27 EDT

(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.

Comment 5 Thomas Watson

2010-07-09 09:55:19 EDT

(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.