From 6f169945f430de6ea396235c0168cf818ca85774 Mon Sep 17 00:00:00 2001
From: Colin O'Dell <colinodell@gmail.com>
Date: Sun, 13 Feb 2022 10:39:17 -0500
Subject: [PATCH] Deprecate MarkdownRendererInterface in favor of new
 DocumentRendererInterface

---
 CHANGELOG.md                               |  7 +++++-
 src/Renderer/DocumentRendererInterface.php | 28 ++++++++++++++++++++++
 src/Renderer/HtmlRenderer.php              |  2 +-
 src/Renderer/MarkdownRendererInterface.php |  2 ++
 src/Xml/MarkdownToXmlConverter.php         |  4 ++--
 src/Xml/XmlRenderer.php                    |  4 ++--
 6 files changed, 41 insertions(+), 6 deletions(-)
 create mode 100644 src/Renderer/DocumentRendererInterface.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c27e9b0fd..300dd52036 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,12 @@ Updates should follow the [Keep a CHANGELOG](https://keepachangelog.com/) princi
 
 ### Added
 
- - Added new `EmbedExtension` (#805)
+- Added new `EmbedExtension` (#805)
+- Added `DocumentRendererInterface` as a replacement for the now-deprecated `MarkdownRendererInterface`
+
+### Deprecated
+
+- Deprecated `MarkdownRendererInterface`; use `DocumentRendererInterface` instead
 
 ## [2.2.3] - 2022-02-26
 
diff --git a/src/Renderer/DocumentRendererInterface.php b/src/Renderer/DocumentRendererInterface.php
new file mode 100644
index 0000000000..dd34dd6b39
--- /dev/null
+++ b/src/Renderer/DocumentRendererInterface.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the league/commonmark package.
+ *
+ * (c) Colin O'Dell <colinodell@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace League\CommonMark\Renderer;
+
+use League\CommonMark\Node\Block\Document;
+use League\CommonMark\Output\RenderedContentInterface;
+
+/**
+ * Renders a parsed Document AST
+ */
+interface DocumentRendererInterface extends MarkdownRendererInterface
+{
+    /**
+     * Render the given Document node (and all of its children)
+     */
+    public function renderDocument(Document $document): RenderedContentInterface;
+}
diff --git a/src/Renderer/HtmlRenderer.php b/src/Renderer/HtmlRenderer.php
index 618fd8d5bd..ec21166f4e 100644
--- a/src/Renderer/HtmlRenderer.php
+++ b/src/Renderer/HtmlRenderer.php
@@ -25,7 +25,7 @@
 use League\CommonMark\Output\RenderedContent;
 use League\CommonMark\Output\RenderedContentInterface;
 
-final class HtmlRenderer implements MarkdownRendererInterface, ChildNodeRendererInterface
+final class HtmlRenderer implements DocumentRendererInterface, ChildNodeRendererInterface
 {
     /** @psalm-readonly */
     private EnvironmentInterface $environment;
diff --git a/src/Renderer/MarkdownRendererInterface.php b/src/Renderer/MarkdownRendererInterface.php
index 68a8dabd48..83af8cdcf2 100644
--- a/src/Renderer/MarkdownRendererInterface.php
+++ b/src/Renderer/MarkdownRendererInterface.php
@@ -18,6 +18,8 @@
 
 /**
  * Renders a parsed Document AST
+ *
+ * @deprecated since 2.3; use {@link DocumentRendererInterface} instead
  */
 interface MarkdownRendererInterface
 {
diff --git a/src/Xml/MarkdownToXmlConverter.php b/src/Xml/MarkdownToXmlConverter.php
index f74a9a614a..cf1da67b3a 100644
--- a/src/Xml/MarkdownToXmlConverter.php
+++ b/src/Xml/MarkdownToXmlConverter.php
@@ -18,7 +18,7 @@
 use League\CommonMark\Output\RenderedContentInterface;
 use League\CommonMark\Parser\MarkdownParser;
 use League\CommonMark\Parser\MarkdownParserInterface;
-use League\CommonMark\Renderer\MarkdownRendererInterface;
+use League\CommonMark\Renderer\DocumentRendererInterface;
 
 final class MarkdownToXmlConverter implements ConverterInterface
 {
@@ -26,7 +26,7 @@ final class MarkdownToXmlConverter implements ConverterInterface
     private MarkdownParserInterface $parser;
 
     /** @psalm-readonly */
-    private MarkdownRendererInterface $renderer;
+    private DocumentRendererInterface $renderer;
 
     public function __construct(EnvironmentInterface $environment)
     {
diff --git a/src/Xml/XmlRenderer.php b/src/Xml/XmlRenderer.php
index 911a137d41..db29aa45f5 100644
--- a/src/Xml/XmlRenderer.php
+++ b/src/Xml/XmlRenderer.php
@@ -11,10 +11,10 @@
 use League\CommonMark\Node\StringContainerInterface;
 use League\CommonMark\Output\RenderedContent;
 use League\CommonMark\Output\RenderedContentInterface;
-use League\CommonMark\Renderer\MarkdownRendererInterface;
+use League\CommonMark\Renderer\DocumentRendererInterface;
 use League\CommonMark\Util\Xml;
 
-final class XmlRenderer implements MarkdownRendererInterface
+final class XmlRenderer implements DocumentRendererInterface
 {
     private const INDENTATION = '    ';