diff --git a/defaults/main.yml b/defaults/main.yml
index 5b1b3b4..0b8ad6c 100644
--- a/defaults/main.yml
+++ b/defaults/main.yml
@@ -3,9 +3,15 @@ smb_packages:
   - cifs-utils
 
 # @var smb_shares:description: >
-# Add mount defined samba shares. You can specify samba credentials with
-# username/password parameter. Credentials will be used in a credentials file
-# and saved to `/root/.smbcredentials/<name>` and not in the fstab directly.
+# Mount defined samba shares. You can specify samba credentials with the
+# `username` and `password` parameter. Given credentials will be used in a secrets file
+# and saved to `/root/.smbcredentials/<name>` instead of the direct use in `/etc/fstab`.
+# If secrets are defined for a list item, the secrest file will also be passed automatically
+# to `mountopts`.
+#
+# The `state` parameter is related to the possible state values of Ansibles
+# [mount](https://docs.ansible.com/ansible/latest/modules/mount_module.html) module.
+# @end
 
 # @var smb_shares:example: >
 # smb_shares:
@@ -19,4 +25,5 @@ smb_packages:
 #       - uid=1000
 #       - gid=1000
 #     state: mounted
+# @end
 smb_shares: []