Add docstrings to meraki module utility methods

PR #41369

Co-authored-by: Kevin Breit <kevin.breit@kevinbreit.net>

lib/ansible/module_utils/network/meraki/meraki.py

@@ -87,6 +87,7 @@ class MerakiModule(object):
                          'devices': '/networks/{net_id}/devices',
                          }
 
+        # Used to retrieve only one item
         self.get_one_urls = {'organizations': '/organizations/{org_id}',
                              'network': '/networks/{net_id}',
                              }
@@ -103,7 +104,7 @@ class MerakiModule(object):
         if self.module._debug or self.params['output_level'] == 'debug':
             self.module.warn('Enable debug output because ANSIBLE_DEBUG was set or output_level is set to debug.')
 
-        # TODO: This needs to be tested
+        # TODO: This should be removed as org_name isn't always required
         self.module.required_if = [('state', 'present', ['org_name']),
                                    ('state', 'absent', ['org_name']),
                                    ]
@@ -116,21 +117,19 @@ class MerakiModule(object):
                         }
 
     def define_protocol(self):
-        ''' Set protocol based on use_https parameters '''
+        """Set protocol based on use_https parameters."""
         if self.params['use_https'] is True:
             self.params['protocol'] = 'https'
         else:
             self.params['protocol'] = 'http'
 
     def is_update_required(self, original, proposed, optional_ignore=None):
-        ''' Compare original and proposed data to see if an update is needed '''
+        """Compare original and proposed data to see if an update is needed."""
         is_changed = False
         ignored_keys = ('id', 'organizationId')
         if not optional_ignore:
             optional_ignore = ('')
 
-        # self.fail_json(msg="Update required check", original=original, proposed=proposed)
-
         for k, v in original.items():
             try:
                 if k not in ignored_keys and k not in optional_ignore:
@@ -150,12 +149,14 @@ class MerakiModule(object):
         return is_changed
 
     def get_orgs(self):
-        ''' Downloads all organizations '''
+        """Downloads all organizations for a user."""
         return self.request('/organizations', method='GET')
 
     def is_org_valid(self, data, org_name=None, org_id=None):
-        ''' Checks whether a specific org exists and is duplicated '''
+        """Checks whether a specific org exists and is duplicated.
-        ''' If 0, doesn't exist. 1, exists and not duplicated. >1 duplicated '''
+
+        If 0, doesn't exist. 1, exists and not duplicated. >1 duplicated.
+        """
         org_count = 0
         if org_name is not None:
             for o in data:
@@ -168,9 +169,10 @@ class MerakiModule(object):
         return org_count
 
     def get_org_id(self, org_name):
-        ''' Returns an organization id based on organization name, only if unique
+        """Returns an organization id based on organization name, only if unique.
-            If org_id is specified as parameter, return that instead of a lookup
+
-        '''
+        If org_id is specified as parameter, return that instead of a lookup.
+        """
         orgs = self.get_orgs()
         # self.fail_json(msg='ogs', orgs=orgs)
         if self.params['org_id'] is not None:
@@ -188,6 +190,7 @@ class MerakiModule(object):
                     return str(i['id'])
 
     def get_nets(self, org_name=None, org_id=None):
+        """Downloads all networks in an organization."""
         if org_name:
             org_id = self.get_org_id(org_name)
         path = self.construct_path('get_all', org_id=org_id)
@@ -195,7 +198,8 @@ class MerakiModule(object):
         return r
 
     def get_net(self, org_name, net_name, data=None):
-        ''' Return network information '''
+        """Return network information about a particular network."""
+        # TODO: Allow method to download data on its own
         # if not data:
         #     org_id = self.get_org_id(org_name)
         #     path = '/organizations/{org_id}/networks/{net_id}'.format(
@@ -213,7 +217,7 @@ class MerakiModule(object):
         return False
 
     def get_net_id(self, org_name=None, net_name=None, data=None):
-        ''' Return network id from lookup or existing data '''
+        """Return network id from lookup or existing data."""
         if data is None:
             self.fail_json(msg='Must implement lookup')
         for n in data:
@@ -222,6 +226,10 @@ class MerakiModule(object):
         self.fail_json(msg='No network found with the name {0}'.format(net_name))
 
     def construct_path(self, action, function=None, org_id=None, net_id=None, org_name=None):
+        """Build a path from the URL catalog.
+
+        Uses function property from class for catalog lookup.
+        """
         built_path = None
         if function is None:
             built_path = self.url_catalog[action][self.function]
@@ -234,7 +242,7 @@ class MerakiModule(object):
         return built_path
 
     def request(self, path, method=None, payload=None):
-        ''' Generic HTTP method for Meraki requests '''
+        """Generic HTTP method for Meraki requests."""
         self.path = path
         self.define_protocol()
 
@@ -259,6 +267,7 @@ class MerakiModule(object):
             pass
 
     def exit_json(self, **kwargs):
+        """Custom written method to exit from module."""
         self.result['response'] = self.response
         self.result['status'] = self.status
         # Return the gory details when we need it
@@ -270,6 +279,7 @@ class MerakiModule(object):
         self.module.exit_json(**self.result)
 
     def fail_json(self, msg, **kwargs):
+        """Custom written method to return info on failure."""
         self.result['response'] = self.response
         self.result['status'] = self.status