44 * Indicates if the object can go back. If true this indicates that 45 * there is /back session history/ \available for navigation\. 50 * Indicates if the object can go forward. If true this indicates that 51 * there is /forward session history/ \available for navigation\ 1. /.../ are awkward 2. \...\ are awkward 3. there's a period at the end of 45 but not at the end of 51. Does goBack() use the DOM Model, or is it always cache? I suspect it's dom, in which case the comment is probably wrong: When 57 * a page is loaded from session history, all content is loaded from the 58 * cache (if available) and page state (such as form values, scroll position) 59 * is restored. Is 'you' appropriate for javadoc? 84 * likely you can't goto that index another missing period at EOComment. 103 * Meta-refresh flag. The cache is bypassed. This type of load is Perhaps Bypass cache? do we really mean passive? Isn't this for a verb where something is telling webnavigation what to do? 126 const unsigned long LOAD_FLAGS_BYPASS_PROXY = 0x0200; // Bypass the proxy while there are only 2 caches (memory and disk), there may be 0 .. Inf proxies. Bypassing 'the proxy' is probably incorrect. 138 * @param referrer - The referring URI. If this argument is NULL, the 139 * referring URI will be inferred internally. what does 'inferred internally' mean? 168 * pending Javascript timeouts. JavaScript 185 * Retrieves the current DOM document for the WebBrowser. It doesn't retrieve, it *is*. It's an attribute after all. The method getDocument retrieves. 186 */ 187 readonly attribute nsIDOMDocument document; 138 * @param referrer - The referring URI. If this argument is NULL, the 139 * referring URI will be inferred internally. 144 in nsIURI referrer, 195 * The refering URI. this is misspelled. 196 */ 197 readonly attribute nsIURI referingURI; Please address these before seriously considering freezing this interface.

-> Rick

Good call in cc'ing me, timeless: I like fixing docs. I'm willing to take and fix this bug on one condition: someone needs to tell me how they want it formatted. biesi's comments in bug 99625 help, but I need to see some sort of specific reference on how javadoc works.

(In reply to comment #0) > Does goBack() use the DOM Model, or is it always cache? Neither bz nor I can figure out how DOM has anything to do with back/forward operations. > Is 'you' appropriate for javadoc? Per the documentation of canGoBack, changing "you" to "the object". > 103 * Meta-refresh flag. The cache is bypassed. This type of load is > Perhaps Bypass cache? do we really mean passive? Isn't this for a verb where something is telling webnavigation what to do? Considering how I understand meta refresh tags to work, "Bypass the cache." will replace the phrase "The cache is bypassed." > 126 const unsigned long LOAD_FLAGS_BYPASS_PROXY = 0x0200; // Bypass the proxy > while there are only 2 caches (memory and disk), there may be 0 .. Inf proxies. Bypassing 'the proxy' is probably incorrect. As far as I can tell, this particular flag means don't put the page being loaded into the history. bz says the proxy stuff isn't really implemented, and may be "axed". > 138 * @param referrer - The referring URI. If this argument is NULL, the > 139 * referring URI will be inferred internally. > what does 'inferred internally' mean? Hm, as far as I can tell, if the argument is null, then the argument is null, and that is the end of it. Also note the docs for loadURI get the argument names wrong and leave out the headers stream. Proposed text: * @param aUri - The URI string to load. * @param aLoadFlags - Flags modifying load behaviour. Generally you will pass * LOAD_FLAGS_NONE for this parameter. * @param aReferringURI - The referring URI. * @param aPostStream - nsIInputStream containing POST data for the request. * @param aHeaderStream - nsIInputStream containing headers for the request. */ void loadURI(in wstring aUri, in unsigned long aLoadFlags, in nsIURI aReferringURI, in nsIInputStream aPostStream, in nsIInputStream aHeaderStream); > 185 * Retrieves the current DOM document for the WebBrowser. > It doesn't retrieve, it *is*. It's an attribute after all. The method getDocument retrieves. Changing to "References". Other than that, not changing current docs: * References the current DOM document for the frame, or lazily creates a * blank document if there is none. This attribute never returns null except * for unexpected error situations. The "referer" and "refering" bits were probably fixed by an attachment to bug 106386. Other than that, punctuation changes (mostly adding commas) and one instance of "Object" becoming "object". I don't dare make any other changes to my local copy until someone helps me out a bit more with tracking this code down. (These are just educated guesses from my standpoint.)