docs(templates): fully document ITemplateManager

lib/public/Template/ITemplateManager.php

@@ -12,32 +12,58 @@
 use OCP\AppFramework\Http\TemplateResponse;
 
 /**
+ * Provides helpers for locating and rendering server-side templates.
+ *
  * @since 32.0.0
  */
 interface ITemplateManager {
 	/**
-	 * @param TemplateResponse::RENDER_AS_* $renderAs
+	 * Create a template for the given app and template name.
+	 *
+	 * @param string $app App identifier that owns the template
+	 * @param string $name Template name without extension
+	 * @param TemplateResponse::RENDER_AS_* $renderAs Rendering mode / layout wrapper
+	 * @param bool $registerCall Whether to register the request for CSRF token injection
 	 * @throws TemplateNotFoundException if the template cannot be found
 	 * @since 32.0.0
 	 */
 	public function getTemplate(string $app, string $name, string $renderAs = TemplateResponse::RENDER_AS_BLANK, bool $registerCall = true): ITemplate;
 
 	/**
-	 * Shortcut to print a simple page for guests
+	 * Render and print a guest page.
+	 *
+	 * Assigns the provided parameters to the template before printing it.
+	 * This helper does not set an HTTP status code or terminate execution.
+	 *
+	 * @param string $application App identifier that owns the template
+	 * @param string $name Template name without extension
+	 * @param array $parameters Template variables to assign
 	 * @since 32.0.0
 	 */
 	public function printGuestPage(string $application, string $name, array $parameters = []): void;
 
 	/**
-	 * Print a fatal error page and terminates the script
+	 * Render and print an error page, then terminate execution.
+	 *
+	 * Sets the HTTP status code before rendering. Falls back from the themed
+	 * error page to an unthemed template and finally to plain-text output if
+	 * rendering fails.
+	 *
+	 * @param string $error_msg Error message to show
+	 * @param string $hint Optional hint shown with the error
+	 * @param int $statusCode HTTP status code to send
 	 * @since 32.0.0
-	 * @param string $error_msg The error message to show
-	 * @param string $hint An optional hint message - needs to be properly escape
 	 */
 	public function printErrorPage(string $error_msg, string $hint = '', int $statusCode = 500): never;
 
 	/**
-	 * Print error page using Exception details
+	 * Render and print an exception error page, then terminate execution.
+	 *
+	 * Sets the HTTP status code before rendering. Uses the exception to populate
+	 * the error view and falls back to plain-text output if rendering fails.
+	 *
+	 * @param \Throwable $exception Exception to render
+	 * @param int $statusCode HTTP status code to send
 	 * @since 32.0.0
 	 */
 	public function printExceptionErrorPage(\Throwable $exception, int $statusCode = 503): never;