Bug 49647

Created attachment 19440 [details]
Proposed API and it's implementation

Attached diff shows the proposed API and It's implementation

API: 
ProjectCustomizer.java
  
Implementation:

CategoryModel.java
CategoryView.java
CustomizerDialog.java
CustomizerPane.form
CustomizerPane.java

The CategoryModel could be published later as an interface if necessary. 

Missing SPL in ProjectCustomizer.java.


Javadoc tip: avoid BiCapitalizedWords (with or without <code>) when
they are not in fact meaningful, so you don't confuse readers who are
expecting such names to be important. Javadoc for ProjectCustomizer says

"Support for creating standard ProjectCustomizer dialog."

But ProjectCustomizer does not extend JDialog, it is just a place for
factory methods, so this Javadoc is more confusing than helpful - why
is the Javadoc for the class referring to its own name?? Use something
more descriptive like

"Support for creating dialogs which can be used as project
customizers. The dialog may display multiple panels or categories.
@see org.netbeans.spi.project.ui.CustomizerProvider"

Same in constructor Javadoc, etc. And when referring to
CustomizerProvider, use {@link ...} or @see or at least <code>.
Similarly, avoid abuse of capitalization in Javadoc like

"@param categories Array of Categories to be shown in the dialog."

The Javadoc will already make it clear that the type is Category[],
and "Categories" is bad because there is no such class. Also repeating
the same word as a parameter or type name loses the opportunity to
give a synonym which can help someone understand the word better.
Simply use e.g.

"@param categories list of panels to be shown in the dialog (may not
be empty)"

BTW do not capitalize the description in a @param. Similarly,

"@param componentProvider Implementation of CategoryProvider which
creates components..."

The beginning is just noise; the type is obvious in the generated
Javadoc, and clearly an implementation is wanted, since the type is an
interface. And in fact you mistyped the interface name anyway! Simplify to

"@param componentProvider creator of GUI components..."


createCustomizerDialog should mention if you need to pack() it -
probably not? I assume you need to setVisible(true). Should also
mention if it will be modal or not.


'public' modifier in an interface (CategoryComponentProvider) is
redundant.


Should Category.icon be an Image? Icon seems more normal. Doesn't
really matter I guess.


Shouldn't createCustomizerDialog take a HelpCtx? Even if it isn't
working yet? :-)


Why is it permitted by the impl for preselectedCategory to be null,
but the Javadoc does not mention this possibility? And why is it
permitted by the impl for preselectedCategory to not be a name of any
supplied category?


Would be nice to see a diff of changes in j2seproject to use the new
SPI, as well as comments from someone working on some other project
type confirming that the proposed SPI is satisfactory.

My minor suggestion is save one class by making Category toplevel and
add factory methods from ProjectCustomizer to it. At least there will
not be problem with javadoc for ProjectCustomizer ;-)

Hmm, I'm not sure. The way how it looks like now seems a bit less
confusing to me as all the classes in
org.netbeans.spi.project.ui.support have descriptive names. User can
guess what they should be used for. ProjectCustomizer with the two
innerclasses contains all things needed for creating a customizer,
nicely separated. Having createDialog method in the Catogory may save
one class but it does not logicaly belong into it, IMO.

I agree w/ Petr that it's a bit clearer for Category to be a nested
class, but I don't feel strongly about it.

Created attachment 19622 [details]
Fixed javadoc

Created attachment 19624 [details]
Demo of the API usage

Tried to fix the javadoc flaws mentioned by Jesse. Alsso attached the
demo of the usage. I would like to merge that tomorrow. Still
experimenting w/ the HelpCtx parameter. It should not be necessary as
the help for current panel should be shown. Will see. If I find it
usefull I will add the parameter into the factory method.  

Don't worry too much over Javadoc appearance, that can always be
improved later.

Proposed changes checked in.