improve mlir & mlir_opt property documentation

doc/releases/changelog-dev.md

@@ -351,6 +351,9 @@
 * A broken link was removed in the [Compiler Core](https://docs.pennylane.ai/projects/catalyst/en/stable/modules/mlir.html) documentation page. The link referred to where precompiled decomposition rules were implemented, which has since been refactored.
   [(#2913)](https://github.com/PennyLaneAI/catalyst/pull/2913)
 
+* The documentation for `QJIT.mlir` and `QJIT.mlir_opt` was updated with type hints and docstrings that better reflect the compilation-dependent nature of the properties.
+  [(#2975)](https://github.com/PennyLaneAI/catalyst/pull/2975)
+
 <h3>Contributors ✍️</h3>
 
 This release contains contributions from (in alphabetical order):

frontend/catalyst/jit.py

@@ -614,8 +614,16 @@ def _get_effective_capture_mode(self):
         return capture_option
 
     @property
-    def mlir(self):
-        """Obtain the MLIR representation after canonicalization"""
+    def mlir(self) -> str | None:
+        """The canonicalized MLIR representation of the QJIT object after lowering, if available.
+
+        The MLIR for a program can only be generated once `capture` and `generate_ir` have been run,
+        typically via AOT or JIT compilation.
+
+        Returns:
+            str: The textual MLIR module for the QJIT object.
+            None: If the MLIR has not yet been generated for the program.
+        """
         # Canonicalize the MLIR since there can be a lot of redundancy coming from JAX.
         if not self.mlir_module:
             return None
@@ -626,8 +634,16 @@ def mlir(self):
         return canonicalize(stdin=stdin, options=self.compile_options)
 
     @property
-    def mlir_opt(self):
-        """Obtain the MLIR representation after optimization"""
+    def mlir_opt(self) -> str | None:
+        """The MLIR representation of the QJIT object after optimization, if available.
+
+        The optimized MLIR for a program can only be generated once `capture` and `generate_ir` have
+        been run, typically via AOT or JIT compilation.
+
+        Returns:
+            str: The textual MLIR module after applying the QJIT object's pipelines.
+            None: If MLIR has not yet been generated for the program.
+        """
         if not self.mlir_module:
             return None
         using_python_compiler = self.compiler.is_using_python_compiler(self.mlir_module)