including but not limited to: User Manual, DSL Reference and Javadoc.
This information is used to generate documentation for each Gradle version
on [docs.gradle.org](https://docs.gradle.org/).
The documentation is mostly implemented in Asciidoc
though we use GitHub-flavored Markdown for internal documentation too.

You can generate docs by running `./gradlew :docs:docs`.

   * Ascii.truncate("foobar", 5, "..."); // returns "fo..."
   * }
   *
   * <p><b>Note:</b> This method <i>may</i> work with certain non-ASCII text but is not safe for use
   * with arbitrary Unicode text. It is mostly intended for use with text that is known to be safe
   * for use with it (such as all-ASCII text) and for simple debugging text. When using this method,
   * consider the following:
   *
   * <ul>

   * true when the iterable has fewer than two elements.
   *
   * <p><b>Java 8+ users:</b> Use the equivalent {@link Comparators#isInOrder(Iterable, Comparator)}
   * instead, since the rest of {@code Ordering} is mostly obsolete (as explained in the class
   * documentation).
   */
  public boolean isOrdered(Iterable<? extends T> iterable) {
    Iterator<? extends T> it = iterable.iterator();
    if (it.hasNext()) {

 * an equivalence as a bi-predicate like this: {@code myEquivalence::equivalent}.
 *
 * @author Bob Lee
 * @author Ben Yu
 * @author Gregory Kick
 * @since 10.0 (<a href="https://github.com/google/guava/wiki/Compatibility">mostly
 *     source-compatible</a> since 4.0)
 */
@GwtCompatible
/*
 * The type parameter is <T> rather than <T extends @Nullable> so that we can use T in the

   * requests become more likely to trigger expensive operations (a more extreme case of this
   * example is when a server has just booted, and it is mostly busy with getting itself up to
   * speed).
   *
   * To deal with such scenarios, we add an extra dimension, that of "past underutilization",

  private static boolean isTryEnter(Method method) {
    return method.getName().startsWith("tryEnter");
  }

  /**
   * Identifies just enterIfXxx methods (a subset of {@link #isAnyEnter}), which are mostly like the
   * enterXxx methods but behave like tryEnterXxx in some scenarios.
   */
  private static boolean isEnterIf(Method method) {
    return method.getName().startsWith("enterIf");
  }

      rawSource.use {
        val source = rawSource.buffer()
        val urlLine = source.readUtf8LineStrict()
        // Choice here is between failing with a correct RuntimeException
        // or mostly silently with an IOException
        url = urlLine.toHttpUrlOrNull() ?: throw IOException("Cache corruption for $urlLine").also {
          Platform.get().log("cache corruption", WARN, it)
        }

		return nil, err
	}

	// The ZIP format has a sad state of affairs regarding character encoding.
	// Officially, the name and comment fields are supposed to be encoded
	// in CP-437 (which is mostly compatible with ASCII), unless the UTF-8
	// flag bit is set. However, there are several problems:
	//
	//	* Many ZIP readers still do not support UTF-8.

<abbr title="Central Processing Unit - Zentrale Verarbeitungseinheit">CPU</abbr>
<abbr title="too long; didn't read - zu lang; hab's nicht gelesen"><strong>TL;DR:</strong></abbr>
```

    }
  }

  /**
   * This verifies that putUnencodedChars(String) and hashUnencodedChars(String) are equivalent,
   * even for funny strings composed by (possibly unmatched, and mostly illegal) surrogate
   * characters. (But doesn't test that they do the right thing - just their consistency).
   */
  private static void assertHashStringWithSurrogatesEquivalence(