From d69b35f4bc54585e29b4d7c303728f575f617da7 Mon Sep 17 00:00:00 2001
From: jdlrobson <jdlrobson@gmail.com>
Date: Tue, 20 Mar 2018 09:28:03 -0700
Subject: [PATCH] Adjust expectations for API consumers when using the
 TextExtracts API

Bug: T170617
Change-Id: I53e08db40e5319019c842869f992bac32b1dac97
---
 i18n/en.json                  |  4 +++-
 i18n/qqq.json                 |  4 +++-
 includes/ApiQueryExtracts.php | 15 +++++++++++++--
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/i18n/en.json b/i18n/en.json
index c84dba3..af7d7a9 100644
--- a/i18n/en.json
+++ b/i18n/en.json
@@ -14,5 +14,7 @@
 	"apihelp-query+extracts-example-1": "Get a 175-character extract",
 	"apiwarn-textextracts-limit": "<var>exlimit</var> was too large for a whole article extracts request, lowered to $1.",
 	"apiwarn-textextracts-unsupportedmodel": "$1 has content model $2, which is not supported; returning an empty extract.",
-	"apiwarn-textextracts-title-in-file-namespace": "Extract for a title in File namespace was requested, none returned."
+	"apiwarn-textextracts-title-in-file-namespace": "Extract for a title in File namespace was requested, none returned.",
+	"apiwarn-textextracts-sentences-and-html": "The <var>$1sentences</var> parameter may have unexpected results when used in HTML mode.",
+	"apiwarn-textextracts-malformed-html": "HTML may be malformed and/or unbalanced and may omit inline images. Use at your own risk. Known problems are listed at https://www.mediawiki.org/wiki/Extension:TextExtracts#Caveats."
 }
diff --git a/i18n/qqq.json b/i18n/qqq.json
index 8b86f0e..360e6e3 100644
--- a/i18n/qqq.json
+++ b/i18n/qqq.json
@@ -16,5 +16,7 @@
 	"apihelp-query+extracts-example-1": "{{doc-apihelp-example|query+extracts}}",
 	"apiwarn-textextracts-limit": "{{doc-apierror}}\n\nParameters:\n* $1 - Limit that will be used",
 	"apiwarn-textextracts-unsupportedmodel": "{{doc-apierror}}\n\nParameters:\n* $1 - Page title\n* $2 - Content model",
-	"apiwarn-textextracts-title-in-file-namespace": "{{doc-apierror}}\n\nWarning message displayed when an extract for a title in File namespace is requested."
+	"apiwarn-textextracts-title-in-file-namespace": "{{doc-apierror}}\n\nWarning message displayed when an extract for a title in File namespace is requested.",
+	"apiwarn-textextracts-sentences-and-html": "{{doc-apierror}}\n\nWarning message displayed documenting a known issue with sentence parameter used.",
+	"apiwarn-textextracts-malformed-html": "{{doc-apierror}}\n\nWarning message displayed documented known issues with the TextExtracts API."
 }
diff --git a/includes/ApiQueryExtracts.php b/includes/ApiQueryExtracts.php
index 2c025f9..7c4d319 100644
--- a/includes/ApiQueryExtracts.php
+++ b/includes/ApiQueryExtracts.php
@@ -42,6 +42,11 @@ class ApiQueryExtracts extends ApiQueryBase {
 	 */
 	const CACHE_VERSION = 2;
 
+	/**
+	 * @var string
+	 */
+	const PREFIX = 'ex';
+
 	/**
 	 * @var ParserOptions
 	 */
@@ -66,7 +71,7 @@ class ApiQueryExtracts extends ApiQueryBase {
 	 * @return ApiQueryExtracts
 	 */
 	public function __construct( $query, $moduleName, Config $conf ) {
-		parent::__construct( $query, $moduleName, 'ex' );
+		parent::__construct( $query, $moduleName, self::PREFIX );
 		$this->config = $conf;
 	}
 
@@ -109,10 +114,16 @@ class ApiQueryExtracts extends ApiQueryBase {
 				$text = '';
 				$titleInFileNamespace = true;
 			} else {
+				$params = $this->params;
 				$text = $this->getExtract( $t );
 				$text = $this->truncate( $text );
-				if ( $this->params['plaintext'] ) {
+				if ( $params['plaintext'] ) {
 					$text = $this->doSections( $text );
+				} else {
+					if ( $params['sentences'] ) {
+						$this->addWarning( $this->msg( 'apiwarn-textextracts-sentences-and-html', self::PREFIX ) );
+					}
+					$this->addWarning( 'apiwarn-textextracts-malformed-html' );
 				}
 			}