From 4e3024bd63174de4ba8ae788b13eba08af127d63 Mon Sep 17 00:00:00 2001
From: jules <jules@rawmaterialsoftware.com>
Date: Sat, 6 Jul 2013 09:49:22 +0100
Subject: [PATCH] Updated some documentation.

---
 .../juce_gui_basics/windows/juce_CallOutBox.h | 22 ++++++++++++-------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/modules/juce_gui_basics/windows/juce_CallOutBox.h b/modules/juce_gui_basics/windows/juce_CallOutBox.h
index 36b9488a7e..895b2f9b92 100644
--- a/modules/juce_gui_basics/windows/juce_CallOutBox.h
+++ b/modules/juce_gui_basics/windows/juce_CallOutBox.h
@@ -37,16 +37,19 @@
     other component - but it looks fancier, and has an arrow that can indicate the
     object that it applies to.
 
-    Normally, you'd create one of these on the stack and run it modally, e.g.
+    The class works best when shown modally, but obviously running modal loops is
+    evil and must never be done, so the launchAsynchronously method is provided as
+    a handy way of launching an instance of a CallOutBox and automatically managing
+    its lifetime, e.g.
 
     @code
-    void mouseUp (const MouseEvent& e)
+    void mouseUp (const MouseEvent&)
     {
-        MyContentComponent content;
-        content.setSize (300, 300);
+        FoobarContentComp* content = new FoobarContentComp();
+        content->setSize (300, 300);
 
-        CallOutBox callOut (content, *this, nullptr);
-        callOut.runModalLoop();
+        CallOutBox& myBox
+            = CallOutBox::launchAsynchronously (content, getScreenBounds(), nullptr);
     }
     @endcode
 
@@ -97,7 +100,10 @@ public:
 
         This method will create and display a callout, returning immediately, after which
         the box will continue to run modally until the user clicks on some other component, at
-        which point it will be dismissed automatically.
+        which point it will be dismissed and deleted automatically.
+
+        It returns a reference to the newly-created box so that you can customise it, but don't
+        keep a pointer to it, as it'll be deleted at some point when it gets closed.
 
         @param contentComponent     the component to display inside the call-out. This should
                                     already have a size set (although the call-out will also
@@ -130,7 +136,7 @@ public:
     /** @internal */
     bool keyPressed (const KeyPress&) override;
     /** @internal */
-    void handleCommandMessage (int commandId) override;
+    void handleCommandMessage (int) override;
 
 private:
     //==============================================================================