(svn r27084) -Doc: Improve documentation of AllocateWindowDescFront.

src/road_gui.cpp

@@ -841,7 +841,7 @@ static WindowDesc _build_road_scen_desc(
 
 /**
  * Show the road building toolbar in the scenario editor.
- * @return The just opened toolbar.
+ * @return The just opened toolbar, or \c NULL if the toolbar was already open.
  */
 Window *ShowBuildRoadScenToolbar()
 {

src/terraform_gui.cpp

@@ -361,7 +361,7 @@ static WindowDesc _terraform_desc(
 /**
  * Show the toolbar for terraforming in the game.
  * @param link The toolbar we might want to link to.
- * @return The allocated toolbar.
+ * @return The allocated toolbar if the window was newly opened, else \c NULL.
  */
 Window *ShowTerraformToolbar(Window *link)
 {
@@ -763,7 +763,7 @@ static WindowDesc _scen_edit_land_gen_desc(
 
 /**
  * Show the toolbar for terraforming in the scenario editor.
- * @return The allocated toolbar.
+ * @return The allocated toolbar if the window was newly opened, else \c NULL.
  */
 Window *ShowEditorTerraformToolbar()
 {

src/window_gui.h

@@ -848,9 +848,10 @@ Window *FindWindowFromPt(int x, int y);
 
 /**
  * Open a new window.
+ * @tparam Wcls %Window class to use if the window does not exist.
  * @param desc The pointer to the WindowDesc to be created
  * @param window_number the window number of the new window
- * @return see Window pointer of the newly created window
+ * @return %Window pointer of the newly created window, or \c NULL.
  */
 template <typename Wcls>
 Wcls *AllocateWindowDescFront(WindowDesc *desc, int window_number)