Merge lp:~bryce/launchpad/api-doc-fixes into lp:launchpad

[Bryce Harrington]

Improve the bugtask searchTask() parameter documentation, to clarify some items and fill in stub text.

This fills in stub docs for some of the bugtask search fields and makes them a bit more consistent with other api documentation.

[Abel Deuring (adeuring)]

Hi Bryce,

thanks for improving and cleaning up the docs!

I have mostly formal nitpicks: "make lint" says that several lines are too long:

lib/lp/bugs/interfaces/bugtask.py
    780: [C0301] Line too long (87/78)
    789: [C0301] Line too long (90/78)
    822: [C0301] Line too long (97/78)
    827: [C0301] Line too long (190/78)
    834: [C0301] Line too long (90/78)
    842: [C0301] Line too long (87/78)
    864: [C0301] Line too long (136/78)

Could you break the string up so that the line length does not exceed 78 characters? Our typical style looks like this:

    status = List(
        title=_('Status'),
        description=_(
            'Show only bugs with the given status value or list of values.'),
        value_type=Choice(
            title=_('Status'),
            vocabulary=BugTaskStatusSearch,
            default=BugTaskStatusSearch.NEW),
        default=list(DEFAULT_SEARCH_BUGTASK_STATUSES),
        required=False)
    importance = List(
        title=_('Importance'),
        description=_(
            'Show only bugs with the given importance or list of '
            'importances.'),
        value_type=IBugTask['importance'],
        required=False)

> @@ -800,7 +806,7 @@
> statusexplanation = TextLine(
> title=_("Status notes"), required=False)
> has_patch = Bool(
> - title=_('Show only bugs with patches available'), required=False,
> + title=_('Show only bugs with patch attachments.'), required=False,
> default=False)

I am not sure if we should combine the words "patch" and "attachment" in this context: A bug page has two portlets called "patches" and "bug attachments", thus distiguishing between patches and other|ordinary|regular attachments. Naive users might be confused by the term "patch attachment": does it means only patches, or does it mean patches aand/or other attchments? I would prefer to keep the old text to avoid this possible confusion. Alternatively, we could change the text in the portlets to "patch attachments" and "non-patch attachments" or "other attachments" or similar for the sake of consistency and to make the distinction between patches and other attachments more obvious.

[Bryce Harrington (bryce)]

Thanks Abel,

1. I've wrapped the lines and re-checked with make lint.

2. I reverted back to the old wording for 'with patches available'

[Abel Deuring (adeuring)]

Hi Bryce,

thanks for the additional changes! The branch looks good now

review: Approve (code)

=== modified file 'lib/lp/bugs/interfaces/bugtarget.py'
--- lib/lp/bugs/interfaces/bugtarget.py	2010-04-13 16:49:31 +0000
+++ lib/lp/bugs/interfaces/bugtarget.py	2010-05-08 01:43:41 +0000
@@ -156,12 +156,12 @@
         hardware_is_linked_to_bug=Bool(
             title=(
                 u"Search for bugs which are linked to hardware reports "
-                "wich contain the given device or whcih contain a device"
-                "contolled by the given driver."),
+                "which contain the given device or whcih contain a device"
+                "controlled by the given driver."),
             required=False),
         linked_branches=Choice(
             title=(
-                u"Search for bugs that are linked to branches or for bugs"
+                u"Search for bugs that are linked to branches or for bugs "
                 "that are not linked to branches."),
             vocabulary=BugBranchSearch, required=False))
     @operation_returns_collection_of(IBugTask)

=== modified file 'lib/lp/bugs/interfaces/bugtask.py'
--- lib/lp/bugs/interfaces/bugtask.py	2010-04-19 14:47:49 +0000
+++ lib/lp/bugs/interfaces/bugtask.py	2010-05-08 01:43:41 +0000
@@ -774,9 +774,11 @@
 
 class IBugTaskSearchBase(Interface):
     """The basic search controls."""
-    searchtext = TextLine(title=_("Bug ID or text:"), required=False)
+    searchtext = TextLine(title=_("Bug ID or search text."), required=False)
     status = List(
         title=_('Status'),
+        description=_('Show only bugs with the given status value '
+                      'or list of values.'),
         value_type=Choice(
             title=_('Status'),
             vocabulary=BugTaskStatusSearch,
@@ -785,14 +787,20 @@
         required=False)
     importance = List(
         title=_('Importance'),
+        description=_('Show only bugs with the given importance'
+                      'or list of importances.'),
         value_type=IBugTask['importance'],
         required=False)
     assignee = Choice(
-        title=_('Assignee'), vocabulary='ValidAssignee', required=False)
+        title=_('Assignee'),
+        description=_('Person entity assigned for this bug.'),
+        vocabulary='ValidAssignee', required=False)
     bug_reporter = Choice(
-        title=_('Bug Reporter'), vocabulary='ValidAssignee', required=False)
+        title=_('Bug reporter'),
+        description=_('Person entity that filed the bug report.'),
+        vocabulary='ValidAssignee', required=False)
     omit_dupes = Bool(
-        title=_('Omit duplicate bugs'), required=False,
+        title=_('Omit bugs marked as duplicate,'), required=False,
         default=True)
     omit_targeted = Bool(
         title=_('Omit bugs targeted to series'), required=False,
@@ -800,7 +808,7 @@
     statusexplanation = TextLine(
         title=_("Status notes"), required=False)
     has_patch = Bool(
-        title=_('Show only bugs with patches available'), required=False,
+        title=_('Show only bugs with patches available.'), required=False,
         default=False)
     has_no_package = Bool(
         title=_('Exclude bugs with packages specified'),
@@ -808,24 +816,38 @@
     milestone_assignment = Choice(
         title=_('Target'), vocabulary="Milestone", required=False)
     milestone = List(
-        title=_('Target'), value_type=IBugTask['milestone'], required=False)
+        title=_('Milestone'),
+        description=_('Show only bug tasks targeted to this milestone.'),
+        value_type=IBugTask['milestone'], required=False)
     component = List(
-        title=_('Component'), value_type=IComponent['name'], required=False)
+        title=_('Component'),
+        description=_('Distribution package archive grouping. '
+                      'E.g. main, universe, multiverse'),
+        value_type=IComponent['name'], required=False)
     tag = List(title=_("Tag"), value_type=SearchTag(), required=False)
     status_upstream = List(
-        title=_('Status Upstream'),
+        title=_('Status upstream'),
+        description=_('Indicates the status of any remote watches '
+                      'associated with the bug.  Possible values '
+                      'include: pending_bugwatch, hide_upstream, '
+                      'resolved_upstream, and open_upstream.'),
         value_type=Choice(vocabulary=UPSTREAM_STATUS_VOCABULARY),
         required=False)
     has_cve = Bool(
         title=_('Show only bugs associated with a CVE'), required=False)
     bug_supervisor = Choice(
         title=_('Bug supervisor'), vocabulary='ValidPersonOrTeam',
+        description=_('Show only bugs in packages this person or team '
+                      'is subscribed to.'),
         required=False)
     bug_commenter = Choice(
         title=_('Bug commenter'), vocabulary='ValidPersonOrTeam',
+        description=_('Show only bugs commented on by this person.'),
         required=False)
     subscriber = Choice(
         title=_('Bug subscriber'), vocabulary='ValidPersonOrTeam',
+        description=_('Show only bugs this person or team '
+                      'is directly subscribed to.'),
         required=False)
     affects_me = Bool(
         title=_('Show only bugs affecting me'), required=False)
@@ -847,7 +869,9 @@
     one value can be selected.)
     """
     tag = List(
-        title=_("Tags"), description=_("Separated by whitespace."),
+        title=_("Tags"),
+        description=_("String or list of strings for tags to search. "
+                      "To exclude, prepend a '-', e.g. '-unwantedtag'"),
         value_type=SearchTag(), required=False)
     tags_combinator = Choice(
         title=_("Tags combination"),