Github user paulk-asert commented on a diff in the pull request:
https://github.com/apache/groovy/pull/797#discussion_r217899766
--- Diff: subprojects/groovy-yaml/src/spec/doc/yaml-userguide.adoc ---
@@ -0,0 +1,112 @@
+//////////////////////////////////////////
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+//////////////////////////////////////////
+
+= Processing YAML
+
+Groovy comes with integrated support for converting between Groovy objects
and YAML. The classes dedicated to
+YAML serialisation and parsing are found in the `groovy.yaml` package.
+
+[[yaml_yamlslurper]]
+== YamlSlurper
+
+`YamlSlurper` is a class that parses YAML text or reader content into
Groovy data structures (objects) such as maps, lists and
+primitive types like `Integer`, `Double`, `Boolean` and `String`.
+
+The class comes with a bunch of overloaded `parse` methods plus some
special methods such as `parseText`
+and others. For the next example we will use the `parseText` method. It
parses a YAML `String` and recursively converts it to a
+list or map of objects. The other `parse*` methods are similar in that
they return a YAML `String` but for different parameter
+types.
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-yaml/src/spec/test/groovy/yaml/YamlParserTest.groovy
+----
+
+Notice the result is a plain map and can be handled like a normal Groovy
object instance. `YamlSlurper` parses the
+given YAML as defined by the http://yaml.org/spec/1.2/spec.html[YAML
Ainât Markup Language (YAMLâ¢)].
+
+In addition to maps `YamlSlurper` supports YAML arrays which are converted
to lists.
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-yaml/src/spec/test/groovy/yaml/YamlParserTest.groovy
+----
+
+The YAML standard supports the following primitive data types: string,
number, object, `true`, `false` and `null`. `YamlSlurper`
+converts these YAML types into corresponding Groovy types.
+
+[source,groovy]
+----
+include::{rootProjectDir}/subprojects/groovy-yaml/src/spec/test/groovy/yaml/YamlParserTest.groovy
--- End diff --
this is the whole file for a third time. Is this needed?
---
