I spent a couple of hours this friday evening tracking down why all my RST comments in one file disappeared, and I could not see anything wrong with my comments.
I managed to whittle it down to this, the smallest case that reproduces the behaviour.
IDL has no problem with the extra $ after 'begin', but it seems to upset IDLdoc tremedously.
; ------------------ >8 -----------
; One description
if 1 then begin $ ; remove the dollar on this line to restore sanity
print, "hello, "
; This description (and everything from here on) disappears
print, " world!"