The simple scenario for how to create a suggestion is as follows:

1. Obtain a reference to the SuggestionManager:

        SuggestionManager manager = SuggestionManager.getDefault();
      

   Note: this may return null (in the case where the Suggestions module is not available/enabled) so check the return value!

2. Check to make sure that the type of suggestion you're about to add is welcome by the user:

         if (manager.isEnabled(suggestionTypeId) &&
             manager.isObserved(suggestionTypeId)) {
      

3. Create a new {@link org.netbeans.api.tasklist.Suggestion}:

         Suggestion suggestion = manager.createSuggestion(suggestionTypeId,
                                       "my suggestion description",
             new SuggestionPerformer() {
               public void perform(Suggestion s) {
                  beep();
               }
             }
           (two more methods here, both returning null),
           null
         );
         suggestion.setPriority(SuggestionPriority.HIGH);
      

4. Register the suggestion with the SuggestionManager:

         List addList = new ArrayList(1);
         addList.add(suggestion);
         manager.register(suggestionTypeId, addList, null, null);
      

5. You also need to register the Suggestion type for this suggestion with the system. We used suggestionTypeId above; this is just a string with some unique Id, let's say "CopyrightCheck". We need to register this in the module's layer XML file:

       <folder name="Suggestions"> 
           <folder name="Types"> 
               <file name="copyrightcheck.xml" url="copyrightcheck.xml"/>
           </folder>
       </folder>
   

   and then the file copyrightcheck.xml in your module (in the same directory as your layer file) contains something like this:

   <?xml version="1.0"?>
   <!DOCTYPE type PUBLIC "-//NetBeans//DTD suggestion type 1.0//EN" "http://www.netbeans.org/dtds/suggestion-type-1_0.dtd">
   <type
       name='CopyrightCheck'
       description_key='HINT_COPYRIGHT'
       long_description_key='LONGHINT_COPYRIGHT'
       localizing_bundle='com.foo.bar.Bundle'
       icon='nbresloc:/com/foo/bar/copyrightCheck.gif'
   />
   

   The DTD referenced above can be found here.

   Then in your Bundle file identified above, add an entry like:

       HINT_COPYRIGHT=Copyright Problems
       LONGHINT_copyrighttype=Identify copyright notices in files where the copyright year does not include the current year.
   

OpenIDE-Module-Module-Dependencies: org.netbeans.api.tasklist/1 > 1.0

So here's what a complete code segment might look like:

  String suggestionType = "beepid";
  SuggestionManager mgr = SuggestionManager.getDefault();
  if ((mgr != null) && mgr.isEnabled(suggestionType) &&
      mgr.isObserved(suggestionType)) {
     String summary = "Ring the system bell to annoy others";
     SuggestionPerformer performer = new SuggestionPerformer() {
        public void perform(Suggestion s) {
            beep(); beep(); beep();
        }
        public Object getConfirmation(Suggestion s) {
            return "Ring the system bell 3 times, then quit. Will echo \007.";
        }
	public boolean hasConfirmation() {
	    return true;
	}
     });
     Suggestion s = manager.createSuggestion(suggestionType, summary, performer);
     mgr.add(s);
  }