Clarify automgenerated docs for MultiContainerInterface.add_* (#758)

* Clarify automgenerated docs for MultiContainerInterface.add_* * Updated changelog * Update container.py * Update test_multicontainerinterface.py * Update test_multicontainerinterface.py * Update CHANGELOG.md Co-authored-by: Ryan Ly <[email protected]>
hdmf-dev · Aug 27, 2022 · 8888e92 · 8888e92
1 parent 28bc860
commit 8888e92
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,12 @@
 # HDMF Changelog
 
 ## HDMF 3.4.2 (August 26, 2022)
+
+### Minor improvements
+- Updated ``MultiContainerInterface.__make_add`` to clarify the docstring for ``add_*`` methods generated by the function. @oruebel ([#758](https://github.com/hdmf-dev/hdmf/pull/758))
 - Support "allow_none=True" in docval for args with non-None default. @rly ([#757](https://github.com/hdmf-dev/hdmf/pull/757))
+
+### Bug fixes
 - Fixed deploy release CI. @rly ([#759](https://github.com/hdmf-dev/hdmf/pull/759))
 
 ## HDMF 3.4.1 (August 8, 2022)

diff --git a/src/hdmf/container.py b/src/hdmf/container.py
@@ -728,10 +728,10 @@ def _func(self, **kwargs):
 
     @classmethod
     def __make_add(cls, func_name, attr_name, container_type):
-        doc = "Add %s to this %s" % (cls.__add_article(container_type), cls.__name__)
+        doc = "Add one or multiple %s objects to this %s" % (cls.__join(container_type), cls.__name__)
 
         @docval({'name': attr_name, 'type': (list, tuple, dict, container_type),
-                 'doc': 'the %s to add' % cls.__join(container_type)},
+                 'doc': 'one or multiple %s objects to add to this %s' % (cls.__join(container_type),  cls.__name__)},
                 func_name=func_name, doc=doc)
         def _func(self, **kwargs):
             container = getargs(attr_name, kwargs)
@@ -759,7 +759,7 @@ def _func(self, **kwargs):
 
     @classmethod
     def __make_create(cls, func_name, add_name, container_type):
-        doc = "Create %s and add it to this %s" % (cls.__add_article(container_type), cls.__name__)
+        doc = "Create %s object and add it to this %s" % (cls.__add_article(container_type), cls.__name__)
 
         @docval(*get_docval(container_type.__init__), func_name=func_name, doc=doc,
                 returns="the %s object that was created" % cls.__join(container_type), rtype=container_type)

diff --git a/tests/unit/test_multicontainerinterface.py b/tests/unit/test_multicontainerinterface.py
@@ -101,10 +101,12 @@ def test_init_docval(self):
 
     def test_add_docval(self):
         """Test that the docval for the add method is set correctly."""
+        expected_doc = "add_container(containers)\n\nAdd one or multiple Container objects to this Foo"
+        self.assertTrue(Foo.add_container.__doc__.startswith(expected_doc))
         dv = get_docval(Foo.add_container)
         self.assertEqual(dv[0]['name'], 'containers')
         self.assertTupleEqual(dv[0]['type'], (list, tuple, dict, Container))
-        self.assertEqual(dv[0]['doc'], 'the Container to add')
+        self.assertEqual(dv[0]['doc'], 'one or multiple Container objects to add to this Foo')
         self.assertFalse('default' in dv[0])
 
     def test_create_docval(self):