Repository: deepset-ai/haystack

Issue:
Improve the `WhisperTranscriber` API docs
The `run` function in the API reference seems to be missing the return type. This should probably be fixed in the codebase. 



Discussion:
@TuanaCelik I'm not sure about this issue...

My impression is that you are referring to Haystack 1.x

It seems to me that in Haystack 1.x, `run` methods of nodes generally don't have annotated return types. See an example:
https://github.com/deepset-ai/haystack/blob/6665e8ec7f4e1de921fcef57001743c2b1c090af/haystack/nodes/file_classifier/file_type.py#L108

Feel free to explain it better or close this issue...
Ok, I'm happy to close the issue. But for reference I think having return types in these in Haystack 2.0 would help. the difference here is that for other nodes, we can get an understanding of the return type because of other methods: e.g.: retriever `retrieve` method, that's also the same as what the run function returns. 

But for whisper, `transcribe` and `run` seem to return different things. So in a pipeline, it's difficult to understand what it's going to return by looking at the API reference. There is also no explanation in the docstring like many others have. So the only way to know is to go to the documentation page [here](https://docs.haystack.deepset.ai/docs/whisper_transcriber), or try it out.. Or look a the code. I think the API reference for v1 could also be improved in this case.

<img width="972" alt="image" src="https://github.com/deepset-ai/haystack/assets/15802862/7872ef5d-f7cb-4505-b651-5a8fbb04675c">

Hello, can I work on this issue :)
@TuanaCelik I had a look and generally agree with you.

We should focus on:
- improve the docstring of [`transcribe`](https://github.com/deepset-ai/haystack/blob/3ff79d0307db167ce128ac235ac6e5215607dea6/haystack/nodes/audio/whisper_transcriber.py#L78)

- improve the docstring of [`run`](https://github.com/deepset-ai/haystack/blob/3ff79d0307db167ce128ac235ac6e5215607dea6/haystack/nodes/audio/whisper_transcriber.py#L163)

This will have a direct effect on the API reference.


@aazam-gh, yes!

Feel free to ask for clarification or otherwise you can open a PR (after reading the [Contributors Guidelines](https://github.com/deepset-ai/haystack/blob/main/CONTRIBUTING.md)).
@anakin87 Taking a look at the docstring, there isn't much change to be made for both the functions aside from adding the return type to the docstring?

Resolving patch:
diff --git a/haystack/nodes/audio/whisper_transcriber.py b/haystack/nodes/audio/whisper_transcriber.py
--- a/haystack/nodes/audio/whisper_transcriber.py
+++ b/haystack/nodes/audio/whisper_transcriber.py
@@ -91,6 +91,7 @@ def transcribe(
         :param return_segments: If True, returns the transcription for each segment of the audio file. Supported with
         local installation of whisper only.
         :param translate: If True, translates the transcription to English.
+        :return: A dictionary containing the transcription text and metadata like timings, segments etc.
 
         """
         transcript: Dict[str, Any] = {}
@@ -176,6 +177,8 @@ def run(
         :param labels: Ignored
         :param documents: Ignored
         :param meta: Ignored
+        :return: A dictionary containing a list of Document objects, one for each input file.
+
         """
         transcribed_documents: List[Document] = []
         if file_paths:


Test patch: