drupal_add_js() documentation needs more detail

I find this page quite confusing. For example:

• It does not explicitly state that, by passing no parameters, the function returns the existing list of js items. (It would be helpful to me to have this right at the beginning.)
• The parameters might be better at the top instead of the bottom (but it seems lots of pages are in this order).
• The discussion at the top of the page makes little sense unless you are familiar with the parameters (which are presented further down the page).
• The $data parameter should indicate it depends on the value of the 'type' key in the $options parameter.
• The first mention of available constants does not provide any clue as to their purpose.