drm: document the all the atomic iterators

Mostly because I want the links from the newly-added @state functions
to work. But I think explaining when they're useful and that the
implicit one is deprecated is good either way. Slightly repetitive
unfortunately.

Cc: Harry Wentland <harry.wentland@amd.com>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Reviewed-by: Harry Wentland <harry.wentland@amd.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170328155349.5972-3-daniel.vetter@ffwll.ch