Section 14.2.3 of the User manual references a function named: addClientModule

Maybe there was such a function once, but it looks like it must have
changed to 'clientModule' (i.e.: without the 'add' prefix).

Also, it would have been nice to show the call to 'clientModule'
within the scope of a dependencies

closure.

Digging through the examples that come with gradle I found two buld
scripts that made this bit of functionality a lot easier to understand.

The first was:

dependsOn(':shared')
dependencies {
    compile project(':shared')
    clientModule(['compile'], "commons-lang:commons-lang:2.4") {
        dependency("commons-io:commons-io:1.2")
    }
    addConfiguration('spi')
}

libs.jar(appendix: 'spi', confs: ['spi']) {
    fileSet() {
        include('org/gradle/api/')
    }
}

The other one was:

  ...
 dependencies {
    clientModule(['groovy'], "org.codehaus.groovy:groovy-all:1.6-beta-1") {
        dependency("commons-cli:commons-cli:1.0")
    }
    compile project(':groovycDetector')
    testCompile "junit:junit:4.4"
}   

It would have also been helpful had the user manual pointed out that
the overloaded clientModule methods are defined by
org.gradle.api.dependencies.DependencyContainer

Had the signatures of these overloaded methods also been presented
in the user manual right then & there, it would have been nice too.

Finally, not all users who are new to Gradle have ever used Ivy or Maven before,
so the entire concept of the remote repository can't be taken for granted.
I think there should be something in the docs to point out that they're called
"client" modules because the recursive configuration information is presented
directly in the repository's client (i.e.: in the gradle script), rather than in the
server (the repository itself).

What made it all click was seeing an example of an "ivy xml file" in the context of a repository.
Suppose we had a module id of the form:

      [organisation]/[module]/[type]s/[artifact]-[revision].[ext]

For example. let's say you referred to a module dependency
using the module id name: "apache:xerces:xmlParserApis:2.0.2"

If Gradle didn't have the clientModule feature, you'd need to have
an ivy xml file name something like "ivy-2.0.2.xml" with the same
basic information to express the recursive dependency information
within the context of an Ivy repository directory structure that could
look something like this:

  /foobar/ivy-local-repository/apache/xerces/ivys/ivy-2.0.2.xml
  /foobar/ivy-local-repository/apache/xerces/ivys/ivy-2.4.0.xml
  /foobar/ivy-local-repository/apache/xerces/jars/xerces-2.0.2.jar
  /foobar/ivy-local-repository/apache/xerces/jars/xerces-2.4.0.jar
  /foobar/ivy-local-repository/apache/xerces/jars/xmlParserAPIs-2.0.2.jar

Where

• myrepository = /foobar-repository/ivy-local-repository
• organization = apache
• module = xerces
• type = jars
  • artifact = xerces-2.0.2.jar
  • artifact = xerces-2.4.0.jar
  • artifact = xmlParserAPIs-2.0.2.jar
• type = ivys
  • artifact = ivy-2.0.2.xml
  • artifact = ivy-2.4.0.xml

Ok, there comes a point where you definitely want to steer someone
to the Ivy website. Some other links to reference here for more info:
http://www.jaya.free.fr/ivy/doc/tutorial/defaultconf.html and
http://www.jaya.free.fr/ivy/doc/tutorial/build-repository/basic.html

I hope this helps.