fix: support docstrings without type added (#311)

* fix: support docstrings without type info

* test: update goldens

* fix: update spacing

* test: update goldens

* fix: update prefix start/end removal

* test: update goldens

* fix: apply updates

* fix: update comments

* fix: update docstring and refactor recurring variable

Author: dandhlee

docfx_yaml/extension.py

@@ -845,10 +845,15 @@ def _update_friendly_package_name(path):
                         # Find the index of the current default value argument
                         index = len(args) + count - offset_count
 
-                        # Only add defaultValue when str(default) doesn't contain object address string(object at 0x)
-                        # inspect.getargspec method will return wrong defaults which contain object address for some default values, like sys.stdout
-                        if 'object at 0x' not in str(default):
-                            args[index]['defaultValue'] = str(default)
+                        # Only add defaultValue when str(default) doesn't
+                        # contain object address string, for example:
+                        # (object at 0x) or <lambda> at 0x7fed4d57b5e0,
+                        # otherwise inspect.getargspec method will return wrong
+                        # defaults which contain object address for some,
+                        # like sys.stdout.
+                        default_string = str(default)
+                        if 'at 0x' not in default_string:
+                            args[index]['defaultValue'] = default_string
                 # If we cannot find the argument, it is missing a type and was taken out intentionally.
                 except IndexError:
                     pass
@@ -973,12 +978,23 @@ def _update_friendly_package_name(path):
             if arg['id'] in variables:
                 # Retrieve argument info from extracted map of variable info
                 arg_var = variables[arg['id']]
-                arg['var_type'] = arg_var.get('var_type')
                 arg['description'] = arg_var.get('description')
 
-            # Only add arguments with type and description.
-            if not (arg.get('var_type') and arg.get('description')):
+            # Ignore the entry if we're missing the description.
+            if not arg.get('description'):
                 incomplete_args.append(arg)
+                continue
+
+            if (arg_var_type := arg_var.get('var_type')):
+                arg['var_type'] = arg_var_type
+                continue
+
+            # If the type is not documented or missing from type_hint,
+            # ignore the entry.
+            if not arg.get('var_type'):
+                incomplete_args.append(arg)
+                continue
+
 
         # Remove any arguments with missing type or description from the YAML.
         for incomplete_arg in incomplete_args:

tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.yml

@@ -349,7 +349,12 @@ items:
   syntax:
     content: "get_transport_class() -> typing.Type[\n    google.cloud.texttospeech_v1.services.text_to_speech.transports.base.TextToSpeechTransport\n\
       ]"
-    parameters: []
+    parameters:
+    - defaultValue: None
+      description: The name of the desired transport. If none is provided, then the
+        first transport in the registry is used.
+      id: label
+      var_type: str
   type: method
   uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
 - attributes: []

tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.yml

@@ -349,7 +349,12 @@ items:
   syntax:
     content: "get_transport_class() -> typing.Type[\n    google.cloud.texttospeech_v1beta1.services.text_to_speech.transports.base.TextToSpeechTransport\n\
       ]"
-    parameters: []
+    parameters:
+    - defaultValue: None
+      description: The name of the desired transport. If none is provided, then the
+        first transport in the registry is used.
+      id: label
+      var_type: str
   type: method
   uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
 - attributes: []

tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.client.Client.yml

@@ -68,7 +68,17 @@ items:
       \ typing.Sequence\n    ] = (),\n    publisher_options: typing.Union[\n     \
       \   google.cloud.pubsub_v1.types.PublisherOptions, typing.Sequence\n    ] =\
       \ (),\n    **kwargs: typing.Any\n)"
-    parameters: []
+    parameters:
+    - description: The settings for batch publishing.
+      id: batch_settings
+      var_type: typing.Union[<xref uid="google.cloud.pubsub_v1.types.BatchSettings">google.cloud.pubsub_v1.types.BatchSettings</xref>,
+        typing.Sequence]
+    - defaultValue: ()
+      description: The options for the publisher client. Note that enabling message
+        ordering will override the publish retry timeout to be infinite.
+      id: publisher_options
+      var_type: typing.Union[<xref uid="google.cloud.pubsub_v1.types.PublisherOptions">google.cloud.pubsub_v1.types.PublisherOptions</xref>,
+        typing.Sequence]
   type: class
   uid: google.cloud.pubsub_v1.publisher.client.Client
 - attributes: []
@@ -480,7 +490,14 @@ items:
     content: "from_service_account_file(\n    filename: str,\n    batch_settings:\
       \ typing.Union[\n        google.cloud.pubsub_v1.types.BatchSettings, typing.Sequence\n\
       \    ] = (),\n    **kwargs: typing.Any\n) -> google.cloud.pubsub_v1.publisher.client.Client"
-    parameters: []
+    parameters:
+    - description: The path to the service account private key JSON file.
+      id: filename
+      var_type: str
+    - description: The settings for batch publishing.
+      id: batch_settings
+      var_type: typing.Union[<xref uid="google.cloud.pubsub_v1.types.BatchSettings">google.cloud.pubsub_v1.types.BatchSettings</xref>,
+        typing.Sequence]
   type: method
   uid: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_file
 - attributes: []
@@ -527,7 +544,14 @@ items:
     content: "from_service_account_json(\n    filename: str,\n    batch_settings:\
       \ typing.Union[\n        google.cloud.pubsub_v1.types.BatchSettings, typing.Sequence\n\
       \    ] = (),\n    **kwargs: typing.Any\n) -> google.cloud.pubsub_v1.publisher.client.Client"
-    parameters: []
+    parameters:
+    - description: The path to the service account private key JSON file.
+      id: filename
+      var_type: str
+    - description: The settings for batch publishing.
+      id: batch_settings
+      var_type: typing.Union[<xref uid="google.cloud.pubsub_v1.types.BatchSettings">google.cloud.pubsub_v1.types.BatchSettings</xref>,
+        typing.Sequence]
   type: method
   uid: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_json
 - attributes: []
@@ -1087,7 +1111,20 @@ items:
     - description: If publishing the <code>message</code> would exceed the max size
         limit on the backend.
       var_type: pubsub_v1.publisher.exceptions.MessageTooLargeError
-    parameters: []
+    parameters:
+    - description: The topic to publish messages to.
+      id: topic
+      var_type: str
+    - defaultValue: ''
+      description: A bytestring representing the message body. This must be a bytestring.
+      id: data
+      var_type: bytes
+    - defaultValue: _MethodDefault._DEFAULT_VALUE
+      description: A string that identifies related messages for which publish order
+        should be respected. Message ordering must be enabled for this client to use
+        this feature.
+      id: ordering_key
+      var_type: str
   type: method
   uid: google.cloud.pubsub_v1.publisher.client.Client.publish
 - attributes: []
@@ -1113,7 +1150,14 @@ items:
     - description: If the topic/ordering key combination has not been seen before
         by this client.
       var_type: ValueError
-    parameters: []
+    parameters:
+    - description: The topic to publish messages to.
+      id: topic
+      var_type: str
+    - description: A string that identifies related messages for which publish order
+        should be respected.
+      id: ordering_key
+      var_type: str
   type: method
   uid: google.cloud.pubsub_v1.publisher.client.Client.resume_publish
 - attributes: []

tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.futures.Future.yml

@@ -77,7 +77,14 @@ items:
   syntax:
     content: "add_done_callback(\n    callback: typing.Callable[[pubsub_v1.publisher.futures.Future],\
       \ typing.Any]\n) -> None"
-    parameters: []
+    parameters:
+    - description: A callable that will be called with this future as its only argument
+        when the future completes or is cancelled. The callable will always be called
+        by a thread in the same process in which it was added. If the future has already
+        completed or been cancelled then the callable will be called immediately.
+        These callables are called in the order that they were added.
+      id: callback
+      var_type: typing.Callable[[pubsub_v1.publisher.futures.Future], typing.Any]
   type: method
   uid: google.cloud.pubsub_v1.publisher.futures.Future.add_done_callback
 - attributes: []
@@ -197,7 +204,11 @@ items:
       var_type: concurrent.futures.TimeoutError
     - description: For undefined exceptions in the underlying call execution.
       var_type: Exception
-    parameters: []
+    parameters:
+    - defaultValue: None
+      description: The number of seconds before this call times out and raises TimeoutError.
+      id: timeout
+      var_type: typing.Union[int, float]
   type: method
   uid: google.cloud.pubsub_v1.publisher.futures.Future.result
 - attributes: []

tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.client.Client.yml

@@ -673,7 +673,10 @@ items:
   syntax:
     content: "from_service_account_file(\n    filename: str, **kwargs: typing.Any\n\
       ) -> google.cloud.pubsub_v1.subscriber.client.Client"
-    parameters: []
+    parameters:
+    - description: The path to the service account private key json file.
+      id: filename
+      var_type: str
   type: method
   uid: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_file
 - attributes: []
@@ -719,7 +722,10 @@ items:
   syntax:
     content: "from_service_account_json(\n    filename: str, **kwargs: typing.Any\n\
       ) -> google.cloud.pubsub_v1.subscriber.client.Client"
-    parameters: []
+    parameters:
+    - description: The path to the service account private key json file.
+      id: filename
+      var_type: str
   type: method
   uid: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_json
 - attributes: []
@@ -1692,13 +1698,45 @@ items:
       \ = None,\n    use_legacy_flow_control: bool = False,\n    await_callbacks_on_shutdown:\
       \ bool = False,\n) -> google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture"
     parameters:
+    - description: The name of the subscription. The subscription should have already
+        been created (for example, by using <code>create_subscription</code>).
+      id: subscription
+      var_type: str
+    - description: The callback function. This function receives the message as its
+        only argument and will be called from a different thread/ process depending
+        on the scheduling strategy.
+      id: callback
+      var_type: typing.Callable[[subscriber.message.Message], typing.Any]
+    - defaultValue: ()
+      description: The flow control settings. Use this to prevent situations where
+        you are inundated with too many messages at once.
+      id: flow_control
+      var_type: typing.Union[<xref uid="google.cloud.pubsub_v1.types.FlowControl">google.cloud.pubsub_v1.types.FlowControl</xref>,
+        typing.Sequence]
+    - defaultValue: None
+      description: An optional *scheduler* to use when executing the callback. This
+        controls how callbacks are executed concurrently. This object must not be
+        shared across multiple <code>SubscriberClient</code> instances.
+      id: scheduler
+      var_type: typing.Optional[subscriber.scheduler.ThreadScheduler]
     - defaultValue: 'False'
       description: If set to <code>True</code>, flow control at the Cloud Pub/Sub
         server is disabled, though client-side flow control is still enabled. If set
         to <code>False</code> (default), both server-side and client-side flow control
         are enabled.
       id: use_legacy_flow_control
       var_type: bool
+    - defaultValue: 'False'
+      description: If <code>True</code>, after canceling the returned future, the
+        latter's <code>result()</code> method will block until the background stream
+        and its helper threads have been terminated, and all currently executing message
+        callbacks are done processing. If <code>False</code> (default), the returned
+        future's <code>result()</code> method will not block after canceling the future.
+        The method will instead return immediately after the background stream and
+        its helper threads have been terminated, but some of the message callback
+        threads might still be running at that point.
+      id: await_callbacks_on_shutdown
+      var_type: bool
   type: method
   uid: google.cloud.pubsub_v1.subscriber.client.Client.subscribe
 - attributes: []

tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.Future.yml

@@ -194,7 +194,11 @@ items:
       var_type: concurrent.futures.TimeoutError
     - description: If the operation did not succeed for another reason.
       var_type: AcknowledgeError
-    parameters: []
+    parameters:
+    - defaultValue: None
+      description: The number of seconds before this call times out and raises TimeoutError.
+      id: timeout
+      var_type: typing.Union[int, float]
   type: method
   uid: google.cloud.pubsub_v1.subscriber.futures.Future.result
 - attributes: []

tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.message.Message.yml

@@ -69,7 +69,18 @@ items:
     content: 'Message(message: types.PubsubMessage._meta._pb, ack_id: str, delivery_attempt:
       int, request_queue: queue.Queue, exactly_once_delivery_enabled_func: typing.Callable[[],
       bool] = <function Message.<lambda>>)'
-    parameters: []
+    parameters:
+    - description: The ack_id received from Pub/Sub.
+      id: ack_id
+      var_type: str
+    - description: The delivery attempt counter received from Pub/Sub if a DeadLetterPolicy
+        is set on the subscription, and zero otherwise.
+      id: delivery_attempt
+      var_type: int
+    - description: A Callable that returns whether exactly-once delivery is currently-enabled.
+        Defaults to a lambda that always returns False.
+      id: exactly_once_delivery_enabled_func
+      var_type: typing.Callable[[], bool]
   type: method
   uid: google.cloud.pubsub_v1.subscriber.message.Message
 - attributes: []
@@ -369,7 +380,12 @@ items:
     '
   syntax:
     content: 'modify_ack_deadline(seconds: int) -> None'
-    parameters: []
+    parameters:
+    - description: The number of seconds to set the lease deadline to. This should
+        be between 0 and 600. Due to network latency, values below 10 are advised
+        against.
+      id: seconds
+      var_type: int
   type: method
   uid: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline
 - attributes: []
@@ -435,7 +451,12 @@ items:
     '
   syntax:
     content: "modify_ack_deadline_with_response(\n    seconds: int,\n) -> google.cloud.pubsub_v1.subscriber.futures.Future"
-    parameters: []
+    parameters:
+    - description: The number of seconds to set the lease deadline to. This should
+        be between 0 and 600. Due to network latency, values below 10 are advised
+        against.
+      id: seconds
+      var_type: int
   type: method
   uid: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline_with_response
 - attributes: []

tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.yml

@@ -87,7 +87,13 @@ items:
     '
   syntax:
     content: "shutdown(\n    await_msg_callbacks: bool = False,\n) -> typing.List[pubsub_v1.subscriber.message.Message]"
-    parameters: []
+    parameters:
+    - defaultValue: 'False'
+      description: If <code>True</code>, the method will block until all currently
+        executing callbacks are done processing. If <code>False</code> (default),
+        the method will not wait for the currently running callbacks to complete.
+      id: await_msg_callbacks
+      var_type: bool
   type: method
   uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.shutdown
 references:

tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.yml

@@ -21,7 +21,12 @@ items:
   syntax:
     content: "ThreadScheduler(\n    executor: typing.Optional[concurrent.futures.thread.ThreadPoolExecutor]\
       \ = None,\n)"
-    parameters: []
+    parameters:
+    - defaultValue: None
+      description: An optional executor to use. If not specified, a default one will
+        be created.
+      id: executor
+      var_type: typing.Optional[concurrent.futures.thread.ThreadPoolExecutor]
   type: class
   uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
 - &id001
@@ -81,7 +86,13 @@ items:
     '
   syntax:
     content: "shutdown(\n    await_msg_callbacks: bool = False,\n) -> typing.List[pubsub_v1.subscriber.message.Message]"
-    parameters: []
+    parameters:
+    - defaultValue: 'False'
+      description: If <code>True</code>, the method will block until all currently
+        executing executor threads are done processing. If <code>False</code> (default),
+        the method will not wait for the currently running threads to complete.
+      id: await_msg_callbacks
+      var_type: bool
   type: method
   uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.shutdown
 references: