star: update documentation to provide better description of script

Motivation:

Admin was unsure how to generate StAR records.

Modification:

Update defaults to describe which dCache component reacts to the default
values.

Fix some inconsistencies in the documentation.

Result:

Admins should now have a better understanding of how to generate StAR
record.

Target: master
Request: 4.0
Request: 3.2
Request: 3.1
Request: 3.0
Request: 2.16
Require-notes: yes
Require-book: no
Ticket: https://ggus.eu/index.php?mode=ticket_info&ticket_id=131538
Ticket: http://rt.dcache.org/Ticket/Display.html?id=9323
Patch: https://rb.dcache.org/r/10709/
Acked-by: Tigran Mkrtchyan

skel/share/defaults/star.properties

@@ -2,7 +2,15 @@
 #     Default values for Storage Accounting Records (StAR)
 #  -----------------------------------------------------------------------
 @DEFAULTS_HEADER@
-
+#
+#   The StAR records are generated by the 'dcache-star' script, which
+#   an admin typically configures cron to run periodically.  This file
+#   describes the default values used by that script.
+#
+#   Note that, the admin should also install and configure software to
+#   consume these generated records; for example, EGI's "Secure Stomp
+#   Messenger" v2 (SSM2).
+#
 
 #
 #   All records will be identified with the provided site.
@@ -24,9 +32,9 @@ star.storage-system = ${info-provider.se-unique-id}
 #   these directories are created is controlled by the
 #   star.spool.dir-granularity property.
 #
-#   Each time the producer is run, it will create a single file within
-#   one of the auto-created directory.  This file has a filename with
-#   14 hexadecimal characters.
+#   Each time the dcache-star script is run, it will create a single
+#   file within one of the auto-created directory.  This file has a
+#   filename with 14 hexadecimal characters.
 #
 #   For SSM v2, this should be set to /var/spool/apel/outgoing
 #
@@ -47,21 +55,17 @@ star.last-update.path = @dcache.paths.star.state@/last-update
 star.polling-period = 90000
 
 #
-#   Records from the StAR publisher are written into an auto-generated
-#   directory.  Periodically, a new directory is generated that newly
-#   generated records are written into.  This is so each directory
-#   does not contain too many files.
+#   Records from the dcache-star script are written into an
+#   auto-generated directory.  Periodically, a new directory is
+#   generated into which subsequently generated records are written.
+#   This is so each directory does not contain too many files.
 #
 #   The star.spool.dir-granularity property controls how often a new
-#   directory is generate, in minutes.  The value is the duration, in
-#   seconds, that a directory will receive records.
+#   directory is generate.  The value describes for how many minutes a
+#   directory will receive records.
 #
 #   If records are published every n-minutes then a directory will
-#   typically have
-#
-#       star.spool.dir-granularity / n
-#
-#   files.
+#   typically have  star.spool.dir-granularity / n  files.
 #
 star.spool.dir-granularity = 60