diff --git a/reference/exec/functions/shell-exec.xml b/reference/exec/functions/shell-exec.xml
index 2e41113c19..e87b88d33e 100644
--- a/reference/exec/functions/shell-exec.xml
+++ b/reference/exec/functions/shell-exec.xml
@@ -38,8 +38,17 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The output from the executed command or &null; if an error occurred.
+   The output from the executed command or &null; if an error occurred or the
+   command produces no output.
   </para>
+  <note>
+   <para>
+    This function can return &null; both when an error occurs or the program
+    produces no output. It is not possible to detect execution failures using
+    this function. <function>exec</function> should be used when access to the
+    program exit code is required.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="examples">