1273193 - Get Comments webservice docs don’t mention author

Status: NEW

(bugzilla.mozilla.org :: Documentation, defect, P3)

Description

[bbutnaru]

User Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36

Steps to reproduce:

Open first http://bmo.readthedocs.io/en/latest/api/core/v1/comment.html then either https://bugzilla.mozilla.org/rest/bug/comment/75232
or https://bugzilla.mozilla.org/rest/bug/10000/comment

(Using https://bugzilla-dev.allizom.org/ for the latter two URLs works as well.)



Actual results:

The JSON returned from the API contains the field “author” for the comment(s) returned.

The documentation page does not mention that comments can have an “author” property.

For the record, loading a comment via the webservice returned for me: 

{
   "bugs" : {},
   "comments" : {
      "75232" : {
         "attachment_id" : null,
         "author" : "[e-mail]",
         "bug_id" : 10000,
         "creation_time" : "1999-07-16T14:14:17Z",
         "creator" : "[e-mail]",
         "id" : 75232,
         "is_private" : false,
         "raw_text" : "Presumably, this design flaw (witnessed by the\nftp://ftp.mozilla.org/pub/mozilla/nightly/1999-07-15-13-M9/mozilla-win32.zip\ncopy) would apply to OS other than Win32.\n\nProcedure:\n\n0) Cease thinking as a programmer and cast your mind into the naive user's for a\n(painful) moment.\n1) Execute Apprunner.\n2) Open a new window; two Apprunner windows are now loaded.\n3) From the \"File\" menu, in the first window, select the \"Open File or\nLocation...\" dialog.\n4) Repeat action in the second window.\n\nOn the MS taskbar, two \"Open Location\" dialogs now strut. The user who fails to\nclose one window, or performs other tasks between the dialog invocations, or the\nuser who FORGETS may be challenged [ >;+) ] to relate each dialog with it's\ncaller window.\nA keeper of ordering numbers is needed. It has been humbly suggested (in Bug\n8033) that Mozilla should be watchful of where it permits it's tail to sway -\nthat is, should maintain discipline over all of the multiple windows that may be\nopened by the user. A mechanism to identify each Mozilla browser window would\nseem necessary. Implemented, a simple numerical identification (main window 1,\nmain window 2, Wallet HTMLDialog 1.1) of each \"invoking\" browser window would\npermit the user to identify the associations between the dialogs and the\n\"invoker\".\n\nThis thinking may be aided if you assume the programmer's mind once more.",
         "tags" : [],
         "text" : "Presumably, this design flaw[... snip ...]",
         "time" : "1999-07-16T14:14:17Z"
      }
   }
}


Expected results:

The documentation page should mention that comments can have an “author” property. It should also explain the difference between it and the “creator” property, if any.

Comment 1

[bbutnaru]

I just noticed, the “raw_text” field is also missing from the documentation.