Document pitfall about Term / TermFallback classes

Plenty of places in Wikibase have something like this:

    'value' => $term->getText(),
    'language' => $term instanceof TermFallback
        ? $term->getActualLanguageCode()
        : $term->getLanguageCode(),

This is unfortunate, but it’s not entirely clear how we best want to
resolve it (I think Term and TermFallback should be entirely separate
classes – you don’t want a TermFallback in an Item’s TermList either, do
you? – but not 100% sure), nor whether cleaning this up is even worth
the risk of breaking working code. Let’s just document it a bit better
for now.

Change-Id: Ia866ba175c95f0088eae5093bdf684afab83582a

Author: lucaswerkmeister

src/Term/Term.php

@@ -7,6 +7,9 @@
 /**
  * Immutable value object.
  *
+ * Beware that {@link TermFallback} extends this class in an unintuitive way
+ * which arguably even violates the Liskov substitution principle.
+ *
  * @since 0.7.3
  *
  * @license GPL-2.0-or-later
@@ -45,6 +48,11 @@ public function __construct( $languageCode, $text ) {
 	}
 
 	/**
+	 * Language code.
+	 *
+	 * Note that in {@link TermFallback}, this is the *requested* language code,
+	 * and there is a separate {@link TermFallback::getActualLanguageCode()} method.
+	 *
 	 * @return string
 	 */
 	public function getLanguageCode() {