From 529243697a057ad5c109bc1e01799d037da08f53 Mon Sep 17 00:00:00 2001
From: Steve Traylen <steve.traylen@cern.ch>
Date: Sat, 5 Dec 2020 13:28:21 +0100
Subject: [PATCH] Clean up and generate strings docs

Generate REFERENCE.md file correcting some yardoc
syntax errors.

Fixes #38 also
---
 README.md                  |   2 +-
 REFERENCE.md               | 212 +++++++++++++++++++++++++++++++++++++
 manifests/init.pp          |   6 +-
 manifests/install.pp       |   3 +
 manifests/service.pp       |   3 +
 types/database.pp          |   1 +
 types/database/settings.pp |   2 +
 7 files changed, 225 insertions(+), 4 deletions(-)
 create mode 100644 REFERENCE.md

diff --git a/README.md b/README.md
index 557ee45..1de55ba 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,7 @@ nscd::dbconfig:
 ## Usage
 
 Generated puppet strings documentation with examples is available from
-https://voxpupuli.org/puppet-nscd/
+[REFERENCE.md](REFERENCE.md)
 
 ## Authors
 
diff --git a/REFERENCE.md b/REFERENCE.md
new file mode 100644
index 0000000..f7d6d2b
--- /dev/null
+++ b/REFERENCE.md
@@ -0,0 +1,212 @@
+# Reference
+
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## Table of Contents
+
+### Classes
+
+#### Public Classes
+
+* [`nscd`](#nscd): Configures /etc/ncsd.conf and controls nscd service.
+* [`nscd::config`](#nscd--config): == Class nscd::config Configures nscd.
+
+#### Private Classes
+
+* `nscd::install`: installs nscd
+* `nscd::service`: controls nscd service
+
+### Data types
+
+* [`Nscd::Database`](#Nscd--Database): hash of configuration in nscd.conf
+* [`Nscd::Database::Settings`](#Nscd--Database--Settings): all possible settings an nscd database can have
+
+## Classes
+
+### <a name="nscd"></a>`nscd`
+
+nscd class.
+
+Note for each database at least the `enable-cache` key
+must be specified.
+
+#### Examples
+
+##### 
+
+```puppet
+class{'nscd':
+  dbconfigs  => {
+    'passwd' => {'enable-cache'         => true,
+                 'maximum-time-to-live' => 100,
+                 },
+    'group' => {'enable-cache'         => true,
+                'maximum-time-to-live' => 100,
+               },
+
+  }
+```
+
+#### Parameters
+
+The following parameters are available in the `nscd` class:
+
+* [`pkg_ensure`](#-nscd--pkg_ensure)
+* [`service_ensure`](#-nscd--service_ensure)
+* [`service_enable`](#-nscd--service_enable)
+* [`threads`](#-nscd--threads)
+* [`max_threads`](#-nscd--max_threads)
+* [`paranoia`](#-nscd--paranoia)
+* [`restart_interval`](#-nscd--restart_interval)
+* [`user`](#-nscd--user)
+* [`stat_user`](#-nscd--stat_user)
+* [`debug_level`](#-nscd--debug_level)
+* [`reload_count`](#-nscd--reload_count)
+* [`logfile`](#-nscd--logfile)
+* [`dbconfig`](#-nscd--dbconfig)
+
+##### <a name="-nscd--pkg_ensure"></a>`pkg_ensure`
+
+Data type: `Enum['present','absent','latest']`
+
+state of nscd package.
+
+Default value: `'present'`
+
+##### <a name="-nscd--service_ensure"></a>`service_ensure`
+
+Data type: `Boolean`
+
+state of nscd service ensure
+
+Default value: `true`
+
+##### <a name="-nscd--service_enable"></a>`service_enable`
+
+Data type: `Boolean`
+
+state of nscd service enable
+
+Default value: `true`
+
+##### <a name="-nscd--threads"></a>`threads`
+
+Data type: `Integer`
+
+number of threads.
+
+Default value: `5`
+
+##### <a name="-nscd--max_threads"></a>`max_threads`
+
+Data type: `Integer`
+
+maximum number of threads.
+
+Default value: `32`
+
+##### <a name="-nscd--paranoia"></a>`paranoia`
+
+Data type: `Boolean`
+
+enable internal restart mode.
+
+Default value: `false`
+
+##### <a name="-nscd--restart_interval"></a>`restart_interval`
+
+Data type: `Optional[Integer]`
+
+nscd internal restart interval
+
+Default value: `undef`
+
+##### <a name="-nscd--user"></a>`user`
+
+Data type: `String[1]`
+
+specify which user should run nscd
+
+Default value: `'root'`
+
+##### <a name="-nscd--stat_user"></a>`stat_user`
+
+Data type: `Optional[String[1]]`
+
+which users can query statistics
+
+Default value: `undef`
+
+##### <a name="-nscd--debug_level"></a>`debug_level`
+
+Data type: `Integer`
+
+debug level
+
+Default value: `0`
+
+##### <a name="-nscd--reload_count"></a>`reload_count`
+
+Data type: `Integer`
+
+any many reload attempts to make
+
+Default value: `5`
+
+##### <a name="-nscd--logfile"></a>`logfile`
+
+Data type: `Optional[Stdlib::UnixPath]`
+
+specify a debug log file location.
+
+Default value: `undef`
+
+##### <a name="-nscd--dbconfig"></a>`dbconfig`
+
+Data type: `Nscd::Database`
+
+configuration for each of the passwd, group, hosts and service database.
+
+### <a name="nscd--config"></a>`nscd::config`
+
+== Class nscd::config
+Configures nscd.
+
+## Data types
+
+### <a name="Nscd--Database"></a>`Nscd::Database`
+
+hash of configuration in nscd.conf
+
+Alias of
+
+```puppet
+Struct[{
+    Optional['passwd']   => Nscd::Database::Settings,
+    Optional['group']    => Nscd::Database::Settings,
+    Optional['hosts']    => Nscd::Database::Settings,
+    Optional['services'] => Nscd::Database::Settings,
+    Optional['netgroup'] => Nscd::Database::Settings,
+  }]
+```
+
+### <a name="Nscd--Database--Settings"></a>`Nscd::Database::Settings`
+
+all possible settings an nscd database can have
+
+Alias of
+
+```puppet
+Struct[{
+    'enable-cache'                    => Boolean,
+    Optional['positive-time-to-live'] => Integer,
+    Optional['negative-time-to-live'] => Integer,
+    Optional['suggested-size']        => Integer,
+    Optional['check-files']           => Boolean,
+    Optional['persistent']            => Boolean,
+    Optional['shared']                => Boolean,
+    Optional['max-db-size']           => Integer,
+    Optional['auto-propagate']        => Boolean,
+  }]
+```
+
diff --git a/manifests/init.pp b/manifests/init.pp
index 7689f9b..492f5fa 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -22,15 +22,15 @@
 # @param service_enable state of nscd service enable
 # @param threads number of threads.
 # @param max_threads maximum number of threads.
-# @prarm paranoia  enable internal restart mode.
+# @param paranoia  enable internal restart mode.
 # @param restart_interval nscd internal restart interval
 # @param user specify which user should run nscd
 # @param stat_user which users can query statistics
 # @param debug_level debug level
 # @param reload_count any many reload attempts to make
 # @param logfile specify a debug log file location.
-# @dbconfig configuration for each of the passwd, group, hosts and service database.
-
+# @param dbconfig configuration for each of the passwd, group, hosts and service database.
+#
 class nscd (
   Nscd::Database                    $dbconfig,
   Enum['present','absent','latest'] $pkg_ensure       = 'present',
diff --git a/manifests/install.pp b/manifests/install.pp
index daf6107..622a5bc 100644
--- a/manifests/install.pp
+++ b/manifests/install.pp
@@ -1,3 +1,6 @@
+# @summary installs nscd
+# @api private
+#
 class nscd::install (
   $pkg_ensure = $nscd::pkg_ensure
 ) {
diff --git a/manifests/service.pp b/manifests/service.pp
index 3b7fd44..0e0b20f 100644
--- a/manifests/service.pp
+++ b/manifests/service.pp
@@ -1,3 +1,6 @@
+# @summary controls nscd service
+# @api private
+#
 class nscd::service (
   $service_ensure = $nscd::service_ensure,
   $service_enable = $nscd::service_enable,
diff --git a/types/database.pp b/types/database.pp
index 35a88d6..fe65165 100644
--- a/types/database.pp
+++ b/types/database.pp
@@ -1,3 +1,4 @@
+# @summary hash of configuration in nscd.conf
 type Nscd::Database = Struct[
   {
     Optional['passwd']   => Nscd::Database::Settings,
diff --git a/types/database/settings.pp b/types/database/settings.pp
index 5be55d5..986a3de 100644
--- a/types/database/settings.pp
+++ b/types/database/settings.pp
@@ -1,3 +1,5 @@
+# @summary all possible settings an nscd database can have
+#
 type Nscd::Database::Settings = Struct[
   {
     'enable-cache'                    => Boolean,