lowlydba · lowlydba · Aug 30, 2022 · Aug 27, 2022 · Aug 27, 2022 · Aug 27, 2022
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@
 - [Using this collection](#using-this-collection)
   - [Installing the Collection from Ansible Galaxy](#installing-the-collection-from-ansible-galaxy)
 - [Release notes](#release-notes)
-- [Roadmap](#roadmap)
+- [Releasing](#releasing)
 
 ## Modules
 
@@ -29,8 +29,6 @@ If you encounter abusive behavior, please refer to the [policy violations](https
 
 ## Communication
 
-We announce releases and important changes through Ansible's [The Bullhorn newsletter](https://github.com/ansible/community/wiki/News#the-bullhorn). Be sure you are [subscribed](https://eepurl.com/gZmiEP).
-
 Join us in the `#ansible` (general use questions and support), `#ansible-community` (community and collection development questions), and other [IRC channels](https://docs.ansible.com/ansible/devel/community/communication.html#irc-channels).
 
 We take part in the global quarterly [Ansible Contributor Summit](https://github.com/ansible/community/wiki/Contributor-Summit) virtually or in-person. Track [The Bullhorn newsletter](https://eepurl.com/gZmiEP) and join us.
@@ -106,13 +104,31 @@ ansible-galaxy collection install lowlydba.sqlserver:==0.1.0
 
 See [Ansible Using collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for more details.
 
-## Release notes
+## Releasing
+
+### Release notes
 
 See the [changelog](https://github.com/lowlydba/lowlydba.sqlserver/tree/main/CHANGELOG.rst).
 
-## Roadmap
+### Next Release
+
+No major release planned currently.
+
+### Schedule
+
+- Minor releases and patches will aim to be released within 2 weeks of being merged into `main` or when necessary.
+- Non-current minor versions will not generally be patched, since there is little expected breaking of backwards compatibility.
+  - If this does occur, an exception can be made.
+
+### Versioning
+
+This project adheres to [semantic versioning](https://semver.org/) as tracked in [`galaxy.yml`](https://github.com/lowlydba/lowlydba.sqlserver/blob/main/galaxy.yml).
+
+### Deprecation
 
-TBD
+- Deprecations are done by version number (not by date).
+- New deprecations can be added during every minor release, under the condition that they do not break backwards compatibility.
+- Deprecations are expected to have a deprecation cycle of at least 2 major versions (i.e. ~1 year). Maintainers can use a longer deprecation cycle if they want to support the old code for that long.
 
 <!-- Link shortcuts -->
 [dbatools]: https://dbatools.io

diff --git a/changelogs/fragments/119-doc-updates.yml b/changelogs/fragments/119-doc-updates.yml
@@ -0,0 +1,4 @@
+bugfixes:
+  - most modules - fixed alignment, formatting, and typos in module documentation (https://github.com/lowlydba/lowlydba.sqlserver/pull/119).
+  - _SqlServerUtils module_util - added explicit license to private module util (https://github.com/lowlydba/lowlydba.sqlserver/pull/119).
+  - meta/runtime.yml - updated out of date runtime version info (https://github.com/lowlydba/lowlydba.sqlserver/pull/119).
diff --git a/changelogs/fragments/v1-0-2-release-summary.yml b/changelogs/fragments/v1-0-2-release-summary.yml
@@ -0,0 +1 @@
+release_summary: Minor documentation bugfixes and enhancements as requested in the Ansible inclusion process.
diff --git a/galaxy.yml b/galaxy.yml
@@ -2,7 +2,7 @@
 
 namespace: lowlydba
 name: sqlserver
-version: 1.0.1
+version: 1.0.2
 readme: README.md
 authors:
   - John McCall (github.com/lowlydba)

diff --git a/meta/runtime.yml b/meta/runtime.yml
@@ -1,2 +1,2 @@
 ---
-requires_ansible: '>=2.10'
+requires_ansible: ">=2.11"
diff --git a/plugins/module_utils/_SqlServerUtils.psm1 b/plugins/module_utils/_SqlServerUtils.psm1
@@ -1,3 +1,8 @@
+# -*- coding: utf-8 -*-
+
+# (c) 2022, John McCall (@lowlydba)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
 # Private
 
 function Get-LowlyDbaSqlServerAuthSpec {

diff --git a/plugins/modules/ag_listener.py b/plugins/modules/ag_listener.py
@@ -7,7 +7,7 @@
 DOCUMENTATION = r'''
 ---
 module: ag_listener
-short_description: Configures an availability group listener.
+short_description: Configures an availability group listener
 description:
   - Creates an Availability Group Listener for an existing availability group.
 version_added: 0.5.0
@@ -59,9 +59,14 @@
 '''
 
 EXAMPLES = r'''
+- name: Create Availability Group
+  lowlydba.sqlserver.availability_group:
+    sql_instance: sql-01.myco.io
+    ag_name: AG_MyDatabase
+
 - name: Create AG Listener
-  ag_listener:
-    sql_instance_primary: xxx.myco.com
+  lowlydba.sqlserver.ag_listener:
+    sql_instance_primary: sql-01.myco.io
     ag_name: AG_MyDatabase
     listener_name: aglMyDatabase
     ip_address: 10.0.20.20,10.1.77.77

diff --git a/plugins/modules/ag_replica.py b/plugins/modules/ag_replica.py
@@ -7,9 +7,9 @@
 DOCUMENTATION = r'''
 ---
 module: ag_replica
-short_description: Configures an availability group replica.
+short_description: Configures an availability group replica
 description:
-     - Configures an availability group replica.
+  - Configures an availability group replica.
 version_added: 0.5.0
 options:
   sql_instance_replica:
@@ -40,9 +40,8 @@
     default: 'hadr_endpoint'
   endpoint_url:
     description:
-      - By default, the property Fqdn of Get-DbaEndpoint is used as EndpointUrl.
-        Use EndpointUrl if a different URL is required due to special network configurations.
-        EndpointUrl has to be an array of strings in format 'TCP://system-address:port', one entry for every instance.
+      - By default, the property C(Fqdn) of C(Get-DbaEndpoint) is used as I(endpoint_url).
+        Use I(endpoint_url) if a different URL is required due to special network configurations.
     type: str
     required: false
   backup_priority:
@@ -73,7 +72,7 @@
     choices: ['Automatic', 'Manual']
   connection_mode_in_primary_role:
     description:
-        - Which connections can be made to the database when it is in the primary role.
+      - Which connections can be made to the database when it is in the primary role.
     type: str
     required: false
     default: 'AllowAllConnections'
@@ -121,9 +120,14 @@
 '''
 
 EXAMPLES = r'''
+- name: Create Availability Group
+  lowlydba.sqlserver.availability_group:
+    sql_instance: sql-01.myco.io
+    ag_name: AG_MyDatabase
+
 - name: Add a DR replica
   lowlydba.sqlserver.ag_replica:
-    ag_name: 'agMyDatabase'
+    ag_name: 'AG_MyDatabase'
     sql_instance_primary: sql-01.myco.io
     sql_instance_replica: sql-02.myco.io
     failover_mode: 'Manual'

diff --git a/plugins/modules/agent_job.py b/plugins/modules/agent_job.py
@@ -7,7 +7,7 @@
 DOCUMENTATION = r'''
 ---
 module: agent_job
-short_description: Configures a SQL Agent job.
+short_description: Configures a SQL Agent job
 description:
   - Configure a SQL Agent job, including which schedules and category it belongs to.
 version_added: 0.1.0
@@ -68,7 +68,7 @@
 '''
 
 EXAMPLES = r'''
-- name: Create a job schedule
+- name: Create a job
   lowlydba.sqlserver.agent_job:
     sql_instance: sql-01.myco.io
     job: MyJob

diff --git a/plugins/modules/agent_job_category.py b/plugins/modules/agent_job_category.py
@@ -7,9 +7,9 @@
 DOCUMENTATION = r'''
 ---
 module: agent_job_category
-short_description: Configures a SQL Agent job category.
+short_description: Configures a SQL Agent job category
 description:
-  - Creates if it doesn't exist, else does nothing.
+  - Creates if it does not exist, else does nothing.
 version_added: 0.1.0
 options:
   category:
@@ -19,7 +19,7 @@
     type: str
   category_type:
     description:
-      - The type of category. This can be C(LocalJob), C(MultiServerJob) or C(None).
+      - The type of category.
     required: false
     type: str
     choices: ['LocalJob', 'MultiServerJob', 'None']

diff --git a/plugins/modules/agent_job_schedule.py b/plugins/modules/agent_job_schedule.py
@@ -7,7 +7,7 @@
 DOCUMENTATION = r'''
 ---
 module: agent_job_schedule
-short_description: Configures a SQL Agent job schedule.
+short_description: Configures a SQL Agent job schedule
 description:
   - Configures settings for an agent schedule that can be applied to one or more agent jobs.
 version_added: 0.1.0
@@ -20,7 +20,7 @@
   job:
     description:
       - The name of the job that has the schedule.
-      - Schedules and jobs can also be associated via agent_job.
+      - Schedules and jobs can also be associated via M(lowlydba.sqlserver.agent_job).
       - See U(https://docs.dbatools.io/New-DbaAgentSchedule) for more detailed usage.
     type: str
     required: true
@@ -31,29 +31,32 @@
     required: false
   force:
     description:
-      - The force parameter will ignore some errors in the parameters and assume defaults.
-        It will also remove the any present schedules with the same name for the specific job.
-        If I(force=true) the default will be 'Once'.
+      - The force option will ignore some errors in the options and assume defaults.
+      - It will also remove the any present schedules with the same name for the specific job.
     type: bool
   frequency_type:
     description:
       - A value indicating when a job is to be executed.
+      - If I(force=true) the default will be C(Once).
     type: str
     required: false
     choices: ['Once', 'OneTime', 'Daily', 'Weekly', 'Monthly', 'MonthlyRelative', 'AgentStart', 'AutoStart', 'IdleComputer', 'OnIdle']
   frequency_interval:
     description:
       - The days that a job is executed.
-        Allowed values for frequency_type 'Daily' - EveryDay or a number between 1 and 365.
-        Allowed values for frequency_type 'Weekly' - Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Weekdays, Weekend or EveryDay.
-        Allowed values for frequency_type 'Monthly' - Numbers 1 to 31 for each day of the month.
-        If 'Weekdays', 'Weekend' or 'EveryDay' is used it over writes any other value that has been passed before.
-        If I(force=true) the default will be 1.
+      - Allowed values for I(frequency_type=Daily) - C(EveryDay) or a number between C(1) and C(365) inclusive.
+      - >-
+        Allowed values for I(frequency_type=Weekly) -
+        C(Sunday), C(Monday), C(Tuesday), C(Wednesday), C(Thursday), C(Friday), C(Saturday),
+        C(Weekdays), C(Weekend) or C(EveryDay).
+      - Allowed values for I(frequency_type=Monthly) - Numbers C(1) through C(31) for each day of the month.
+      - If C(Weekdays), C(Weekend) or C(EveryDay) is used it overwrites any other value that has been passed before.
+      - If I(force=true) the default will be C(1).
     type: str
     required: false
   frequency_subday_type:
     description:
-      - Specifies the units for the subday frequency_interval.
+      - Specifies the units for the subday I(frequency_interval).
     type: str
     required: false
     choices: ['Time', 'Seconds', 'Minutes', 'Hours']
@@ -64,38 +67,40 @@
     required: false
   frequency_relative_interval:
     description:
-      - A job's occurrence of frequency_interval in each month, if I(frequency_interval=32) ('MonthlyRelative').
+      - A job's occurrence of I(frequency_interval) in each month. If I(frequency_interval=32) (C(MonthlyRelative)).
     type: str
     required: false
     choices: ['Unused', 'First', 'Second', 'Third', 'Fourth', 'Last']
   frequency_recurrence_factor:
     description:
       - The number of weeks or months between the scheduled execution of a job.
-        Required if I(frequency_type='Weekly'), I(frequency_type='Monthly') or I(frequency_type='MonthlyRelative').
+      - Required if I(frequency_type=Weekly), I(frequency_type=Monthly) or I(frequency_type=MonthlyRelative).
     type: int
     required: false
   start_date:
     description:
       - The date on which execution of a job can begin.
-        If force is used the start date will be the current day.
+      - If I(force=true)the start date will be the current day.
+      - Format is C(YYYY-MM-DD).
     type: str
     required: false
   end_date:
     description:
       - The date on which execution of a job can stop.
-        If I(force=true) the end date will be '9999-12-31'
+      - If I(force=true) the end date will be C(9999-12-31).
+      - Format is C(YYYY-MM-DD).
     type: str
     required: false
   start_time:
     description:
-      - The time on any day to begin execution of a job. Format HHMMSS / 24 hour clock.
-      - If I(force=true) the start time will be '00:00:00'
+      - The time on any day to begin execution of a job. Format C(HHMMSS) (24 hour clock).
+      - If I(force=true) the start time will be C(00:00:00).
     type: str
     required: false
   end_time:
     description:
-      - The time on any day to end execution of a job. Format HHMMSS / 24 hour clock.
-        If (force=true) the start time will be '23:59:59'
+      - The time on any day to end execution of a job. Format C(HHMMSS) (24 hour clock).
+      - If (force=true) the start time will be C(23:59:59).
     type: str
     required: false
 author: "John McCall (@lowlydba)"
@@ -112,14 +117,21 @@
 - name: Create a job schedule
   lowlydba.sqlserver.agent_job_schedule:
     sql_instance: sql-01.myco.io
-    schedule: Daily
+    schedule: DailySchedule
     force: true
     enabled: true
     start_date: 2020-05-25  # May 25, 2020
     end_date: 2099-05-25    # May 25, 2099
     start_time: 010500      # 01:05:00 AM
     end_time: 140030        # 02:00:30 PM
     state: present
+
+- name: Create a job with schedule
+  lowlydba.sqlserver.agent_job:
+    sql_instance: sql-01.myco.io
+    job: MyJob
+    force: true
+    schedule: DailySchedule
 '''
 
 RETURN = r'''