diff --git a/docs/04-new-widgets.md b/docs/04-new-widgets.md
index b519d8552..4203f3d3b 100644
--- a/docs/04-new-widgets.md
+++ b/docs/04-new-widgets.md
@@ -1,7 +1,7 @@
 # Creating new widget
 
-All widgets have to be generated via this function so that
-the needed signals are added and mouse input handling is set up.
+All widgets have to be generated by the `wibox.widget.base.make_widget` function
+so that the needed signals are added and mouse input handling is set up.
 
 The returned widget will have a `:buttons` member function that can be used to
 register a set of mouse button events with the widget.
@@ -111,3 +111,8 @@ looks like this:
         widget:after_draw_child(context, cr, child_index, child, width, height)
     end
     widget:after_draw_children(context, cr, width, height)
+
+The `:set_children()` method gets called recursively when setting a widget with
+the declarative layout system, therefore the method should be well defined.
+It should probably hook into the `:add` or `:add_widget` methods or be
+overridden to do nothing.
diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua
index 351984328..2023f6e4e 100644
--- a/lib/wibox/widget/base.lua
+++ b/lib/wibox/widget/base.lua
@@ -504,7 +504,9 @@ local function drill(ids, content)
         end
     end
     -- Replace all children (if any) with the new ones.
-    l:set_children(widgets)
+    if widgets then
+        l:set_children(widgets)
+    end
     return l, id
 end