Upstream ticket:
https://fedorahosted.org/freeipa/ticket/2174

I checked the help, I don't think it was entirely wrong but I was still able to improve it. I think we need to distinguish between topic help ("ipa help migration") and command help ("ipa migrate-ds --help"). Topic help contained examples, it is not a custom that the examples covers _all_ options. But for example a list of related commands was missing in case of migration.

A list of improvements in the migration topic:
  - Add missing list of Topic commands
  - Add one more example to demonstrate migration abilities
  - Add breaks to too long lines to improve readibility

Upstream commits:
master: https://fedorahosted.org/freeipa/changeset/b2239d533d673ea6a92c274c4ab1964bc510184f
ipa-2-2: https://fedorahosted.org/freeipa/changeset/d1cfe47b6c9858c609ac86edd7426bbe64dc03ec

Verfied ... much better!

# ipa help migration
Migration to IPA

Migrate users and groups from an LDAP server to IPA.

This performs an LDAP query against the remote server searching for
users and groups in a container. In order to migrate passwords you need
to bind as a user that can read the userPassword attribute on the remote
server. This is generally restricted to high-level admins such as
cn=Directory Manager in 389-ds (this is the default bind user).

The default user container is ou=People.

The default group container is ou=Groups.

Users and groups that already exist on the IPA server are skipped.

Two LDAP schemas define how group members are stored: RFC2307 and
RFC2307bis. RFC2307bis uses member and uniquemember to specify group
members, RFC2307 uses memberUid. The default schema is RFC2307bis.

The schema compat feature allows IPA to reformat data for systems that
do not support RFC2307bis. It is recommended that this feature is disabled
during migration to reduce system overhead. It can be re-enabled after
migration. To migrate with it enabled use the "--with-compat" option.

Migrated users do not have Kerberos credentials, they have only their
LDAP password. To complete the migration process, users need to go
to http://ipa.example.com/ipa/migration and authenticate using their
LDAP password in order to generate their Kerberos credentials.

Migration is disabled by default. Use the command ipa config-mod to
enable it:

 ipa config-mod --enable-migration=TRUE

If a base DN is not provided with --basedn then IPA will use either
the value of defaultNamingContext if it is set or the first value
in namingContexts set in the root of the remote LDAP server.

EXAMPLES:

 The simplest migration, accepting all defaults:
   ipa migrate-ds ldap://ds.example.com:389

 Specify the user and group container. This can be used to migrate user
 and group data from an IPA v1 server:
   ipa migrate-ds --user-container='cn=users,cn=accounts' \
       --group-container='cn=groups,cn=accounts' \
       ldap://ds.example.com:389

 Since IPA v2 server already contain predefined groups that may collide with
 groups in migrated (IPA v1) server (for example admins, ipausers), users
 having colliding group as their primary group may happen to belong to
 an unknown group on new IPA v2 server.
 Use --group-overwrite-gid option to overwrite GID of already existing groups
 to prevent this issue:
    ipa migrate-ds --group-overwrite-gid \
        --user-container='cn=users,cn=accounts' \
        --group-container='cn=groups,cn=accounts' \
        ldap://ds.example.com:389

 Migrated users or groups may have object class and accompanied attributes
 unknown to the IPA v2 server. These object classes and attributes may be
 left out of the migration process:
    ipa migrate-ds --user-container='cn=users,cn=accounts' \
       --group-container='cn=groups,cn=accounts' \
       --user-ignore-objectclass=radiusprofile \
       --user-ignore-attribute=radiusgroupname \
       ldap://ds.example.com:389

Topic commands:
  migrate-ds  Migrate users and groups from DS to IPA.


Missing and new options are there ...


# ipa help migrate-ds
Purpose: Migrate users and groups from DS to IPA.
Usage: ipa [global-options] migrate-ds LDAP-URI [options]

Positional arguments:
  LDAP-URI              LDAP URI of DS server to migrate from

Options:
  -h, --help            show this help message and exit
  --bind-dn=STR         Bind DN
  --user-container=STR  RDN of container for users in DS relative to base DN
  --group-container=STR
                        RDN of container for groups in DS relative to base DN
  --user-objectclass=STR
                        Comma-separated list of objectclasses used to search
                        for user entries in DS
  --group-objectclass=STR
                        Comma-separated list of objectclasses used to search
                        for group entries in DS
  --user-ignore-objectclass=STR
                        Comma-separated list of objectclasses to be ignored
                        for user entries in DS
  --user-ignore-attribute=STR
                        Comma-separated list of attributes to be ignored for
                        user entries in DS
  --group-ignore-objectclass=STR
                        Comma-separated list of objectclasses to be ignored
                        for group entries in DS
  --group-ignore-attribute=STR
                        Comma-separated list of attributes to be ignored for
                        group entries in DS
  --group-overwrite-gid
                        When migrating a group already existing in IPA domain
                        overwrite the group GID and report as success
  --schema=['RFC2307bis', 'RFC2307']
                        The schema used on the LDAP server. Supported values
                        are RFC2307 and RFC2307bis. The default is RFC2307bis
  --continue            Continuous operation mode. Errors are reported but the
                        process continues
  --base-dn=STR         Base DN on remote LDAP server
  --with-compat         Allows migration despite the usage of compat plugin
  --exclude-groups=STR  comma-separated list of groups to exclude from
                        migration
  --exclude-users=STR   comma-separated list of users to exclude from
                        migration


version ::
ipa-server-2.2.0-4.el6.x86_64

    Technical note added. If any revisions are required, please edit the "Technical Notes" field
    accordingly. All revisions will be proofread by the Engineering Content Services team.
    
    New Contents:
No documentation needed.

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHBA-2012-0819.html