Merge lp:~barry/launchpad/rnr-techdebt into lp:launchpad/db-devel

[Curtis Hovey]

[Curtis Hovey (sinzui)]

Maybe the diff will be sane if we merge into db-devel

[Curtis Hovey (sinzui)]

Hi Barry.

I really appreciate your attention to this issue. I am happy you asked me
to review this because I am familiar with the i18n Answers issues
in the test suite. Your diff must pass this test to be safe to commit.

    iconv -t ascii ~/Desktop/barry.diff > /dev/null

Launchpad code is not i18n enabled, Answers and my editor is! I see
the Arabic portions of the diff right to left. That is very exciting
to see, but made scanning impossible, and when I look at the doctest...well
wow, I cannot read that. I asked Björn read it and his editor refused to
display the file.

You can use .encode .decode to make the words ascii, or use asciismash()
from somewhere in our code. I used both of these when I had to print the
words out. I got tired of that so I just showed the representation.
You can also use ellipsis if you need to hide an awkward part.

You will see a lot of duplication in these tests. I was young and naive
when I wrote them. You can consider deleting any duplication you see when
you fix the encoding issues. There is a small chance that there is a model
or view test that is the definitive test for many of these stories (At least
most of the answers tests are stories)

I see Spanish and Arabic in the diff, I was sure there was some French in
the tests I wrote, but you may not have touched those tests.

> === modified file 'lib/lp/answers/doc/person.txt'
> --- lib/lp/answers/doc/person.txt 2009-12-24 01:41:54 +0000
> +++ lib/lp/answers/doc/person.txt 2010-02-05 12:29:14 +0000
...
> +Language
> +--------
...
> +But Carlos has one.
>
> >>> carlos_raw = personset.getByName('carlos')
> >>> carlos = IQuestionsPerson(carlos_raw)
> >>> for question in carlos.searchQuestions(
> - ... language=[english, spanish]):
> - ... [question.title, question.language.code]
> - [u'Problema al recompilar kernel con soporte smp (doble-n\xfacleo)',
> - u'es']
> -
> -
> -=== needs_attention ===
> -
> -The method accept a parameter called needs_attention which only selects
> -the questions that needs attention from the person. This includes questions
> -owned by the person in the ANSWERED or NEEDSINFO state. It also includes
> -questions on which the person requested for more information or gave an
> -answer and that are back in the OPEN state.
> + ... language=(english, spanish)):
> + ... print question.title, question.language.code
> + Problema al recompilar kernel con soporte smp (doble-núcleo) es

...

> === renamed file 'lib/lp/answers/doc/utility.txt' => 'lib/lp/answers/doc/questionsets.txt'
> --- lib/lp/answers/doc/utility.txt 2009-03-24 12:43:49 +0000
> +++ lib/lp/answers/doc/questionsets.txt 2010-02-05 12:29:14 +0000...

...

> +Searching questions
> +===================
> +
> +The IQuestionSet interface defines a searchQuestions() method that is used to
> +search for questions defined in any question target.
> +
> +
> +Search text
> +-----------
> +
> +The search_text parameter will return questions matching the query using the
> +regular full text algorithm.
>
> >>> for question in question_set.searchQuestions(search_text='firefox'):
> - ... print repr(question.title)...

review: Needs Fixing

[Barry Warsaw (barry)]

Hi Curtis, thanks for the review.

On Feb 05, 2010, at 01:34 PM, Curtis Hovey wrote:

>I really appreciate your attention to this issue. I am happy you asked me
>to review this because I am familiar with the i18n Answers issues
>in the test suite. Your diff must pass this test to be safe to commit.
>
> iconv -t ascii ~/Desktop/barry.diff > /dev/null
>
>Launchpad code is not i18n enabled, Answers and my editor is! I see
>the Arabic portions of the diff right to left. That is very exciting
>to see, but made scanning impossible, and when I look at the doctest...well
>wow, I cannot read that. I asked Björn read it and his editor refused to
>display the file.

Yes, I got too clever because I use a real editor <wink> where all those funny
characters look so beautiful.

>You can use .encode .decode to make the words ascii, or use asciismash()
>from somewhere in our code. I used both of these when I had to print the
>words out. I got tired of that so I just showed the representation.
>You can also use ellipsis if you need to hide an awkward part.

ascii_smash() comes from canonical.encoding and it seems to do a reasonable
job of making iconv happy, while still retaining enough of the original text
for Spanish. I'll have to take ascii_smash()'s word for the Arabic
conversion.

(Aside: I just had to attach a screen shot showing claws-mail's beautiful
handling of the Arabic diff, which right-to-lefts the diff lines. Not sure if
the attachment will come through on the merge-proposal or not. ;)

>You will see a lot of duplication in these tests. I was young and naive
>when I wrote them. You can consider deleting any duplication you see when
>you fix the encoding issues. There is a small chance that there is a model
>or view test that is the definitive test for many of these stories (At least
>most of the answers tests are stories)

I didn't see much duplication among the doctests I touch. I was mostly just
reading through them to get a sense for where I can hack in the R&R stuff. I
didn't touch all the .txt files though (didn't any French for instance). I'll
keep on the lookout for any additional duplication as I work on the R&R stuff.

Here's an incremental diff.

=== modified file 'lib/lp/answers/doc/person.txt'
--- lib/lp/answers/doc/person.txt 2010-02-04 08:24:18 +0000
+++ lib/lp/answers/doc/person.txt 2010-02-05 21:12:48 +0000
@@ -168,12 +168,14 @@

 But Carlos has one.

+ # Because not everyone uses a real editor <wink>
+ >>> from canonical.encoding import ascii_smash
     >>> carlos_raw = personset.getByName('carlos')
     >>> carlos = IQuestionsPerson(carlos_raw)
     >>> for question in carlos.searchQuestions(
     ... language=(english, spanish)):
- ... print question.title, question.language.code
- Problema al recompilar kernel con soporte smp (doble-núcleo) es
+ ... print ascii_smash(question.title), question.language.code
+ Problema al recompilar kernel con soporte smp (doble-nucleo) es

 Questions needing attention

=== modified file 'lib/lp/answers/doc/questionsets.txt'
--- lib/lp/answers/doc/questionsets.txt 2010-02-04 07:27:57 +0000
+++ lib/lp/answers/doc/questionsets.txt 2010-02...

[Curtis Hovey (sinzui)]

Thanks for cleaning up the tests. Sorry for not responding quickly to your reply.

review: Approve (code)

=== modified file 'lib/lp/answers/doc/person.txt'
--- lib/lp/answers/doc/person.txt	2009-12-24 01:41:54 +0000
+++ lib/lp/answers/doc/person.txt	2010-02-10 15:24:19 +0000
@@ -1,22 +1,28 @@
-= Person and the Answer Tracker =
-
-== searchQuestions() ==
-
-IQuestionsPerson defines a searchQuestions() method which can be used to
-select all or a subset of the questions in which the person is
-involved. This includes questions which the person created, is assigned
-to, is subscribed to, commented on, or answered. Various subsets can
-be selected by using the following criteria status, search_text and
-participation type.
-
-    >>> from canonical.launchpad.interfaces import IPersonSet
+=============================
+People and the answer tracker
+=============================
+
+Sometimes you want to find out what questions a person is involved with.
+
+
+Searching
+=========
+
+IQuestionsPerson defines a searchQuestions() method which is used to select
+all, or a subset of, the questions in which a person is involved.  This
+includes questions which the person created, is assigned to, is subscribed to,
+commented on, or answered.  Various subsets can be selected by using the
+various search criteria.
+
+    >>> from lp.registry.interfaces.person import IPersonSet
     >>> from lp.answers.interfaces.questionsperson import IQuestionsPerson
     >>> personset = getUtility(IPersonSet)
     >>> foo_bar_raw = personset.getByEmail('[e-mail]')
     >>> foo_bar = IQuestionsPerson(foo_bar_raw)
 
 
-=== search_text ===
+Search text
+-----------
 
 The search_text parameter will limit the questions to those matching
 the query using the regular full text algorithm.
@@ -28,13 +34,14 @@
     Newly installed plug-in doesn't seem to be used Answered
 
 
-=== sort ===
-
-When using the search_text criteria, the default is to sort the results
-by relevancy. One can use the sort parameter to change that. It takes
-one of the constant defined in the QuestionSort enumeration.
-
-    >>> from canonical.launchpad.interfaces import QuestionSort
+Sorting
+-------
+
+When using the search_text criteria, the default is to sort the results by
+relevancy.  One can use the sort parameter to change that.  It takes one of
+the constant defined in the QuestionSort enumeration.
+
+    >>> from lp.answers.interfaces.questionenums import QuestionSort
     >>> for question in foo_bar.searchQuestions(
     ...         search_text='firefox', sort=QuestionSort.OLDEST_FIRST):
     ...     print question.id, question.title, question.status.title
@@ -42,8 +49,7 @@
     6 Newly installed plug-in doesn't seem to be used Answered
     9 mailto: problem in webpage                      Solved
 
-When no text search is done, the default sort order is
-QuestionSort.NEWEST_FIRST.
+When no text search is done, the default sort order is newest first.
 
     >>> for question in foo_bar.searchQuestions():
     ...     print question.id, question.title, question.status.title
@@ -56,13 +62,13 @@
      4 Firefox loses focus and gets stuck                   Open
 
 
-=== status ===
-
-The last searches showed that by default, not all statuses are searched
-for by default (they excluded expired and invalid questions). The status
-parameter can be used to control the list of statuses to select:
-
-    >>> from canonical.launchpad.interfaces import QuestionStatus
+Status
+------
+
+As shown above, expired and invalid questions are not returned.  The status
+parameter can be used to control the list of statuses to select.
+
+    >>> from lp.answers.interfaces.questionenums import QuestionStatus
     >>> for question in foo_bar.searchQuestions(status=QuestionStatus.INVALID):
     ...     print question.title, question.status.title
     Firefox is slow and consumes too much RAM   Invalid
@@ -70,23 +76,23 @@
 The status parameter can also take a list of statuses.
 
     >>> for question in foo_bar.searchQuestions(
-    ...         status=[QuestionStatus.SOLVED, QuestionStatus.INVALID]):
+    ...         status=(QuestionStatus.SOLVED, QuestionStatus.INVALID)):
     ...     print question.title, question.status.title
     mailto: problem in webpage                  Solved
     Firefox is slow and consumes too much RAM   Invalid
 
 
-=== participation ===
+Participation
+-------------
 
-By default, any types of relationship to a question is considered by
-searchQuestions. This can customized through the participation
-parameter. It takes one or a list of constants from the
-QuestionParticipation enumeration.
+By default, any relationship between a person and a question is considered by
+searchQuestions.  This can customized through the participation parameter.  It
+takes one or a list of constants from the QuestionParticipation enumeration.
 
 To select only questions on which the person commented, the
-QuestionParticipation.COMMENTER is used:
+QuestionParticipation.COMMENTER is used.
 
-    >>> from canonical.launchpad.interfaces import QuestionParticipation
+    >>> from lp.answers.interfaces.questionenums import QuestionParticipation
     >>> for question in foo_bar.searchQuestions(
     ...         participation=QuestionParticipation.COMMENTER, status=None):
     ...     print question.title
@@ -96,8 +102,8 @@
     Installation of Java Runtime Environment for Mozilla
     Newly installed plug-in doesn't seem to be used
 
-QuestionParticipation.SUBSCRIBER will only select the questions to which
-the person is subscribed to:
+QuestionParticipation.SUBSCRIBER will only select the questions to which the
+person is subscribed.
 
     >>> for question in foo_bar.searchQuestions(
     ...         participation=QuestionParticipation.SUBSCRIBER, status=None):
@@ -105,7 +111,7 @@
     Slow system
     Firefox is slow and consumes too much RAM
 
-QuestionParticipation.OWNER selects the questions that the person created:
+QuestionParticipation.OWNER selects the questions that the person created.
 
     >>> for question in foo_bar.searchQuestions(
     ...         participation=QuestionParticipation.OWNER, status=None):
@@ -114,8 +120,8 @@
     Firefox loses focus and gets stuck
     Firefox is slow and consumes too much RAM
 
-QuestionParticipation.ANSWERER selects the questions for which the person
-was marked as the answerer:
+QuestionParticipation.ANSWERER selects the questions for which the person gave
+an answer.
 
     >>> for question in foo_bar.searchQuestions(
     ...         participation=QuestionParticipation.ANSWERER, status=None):
@@ -124,19 +130,18 @@
     Firefox is slow and consumes too much RAM
 
 QuestionParticipation.ASSIGNEE selects that questions which are assigned to
-the person:
+the person.
 
-    >>> for question in foo_bar.searchQuestions(
-    ...         participation=QuestionParticipation.ASSIGNEE, status=None):
-    ...     print question.title
+    >>> list(foo_bar.searchQuestions(
+    ...         participation=QuestionParticipation.ASSIGNEE, status=None))
+    []
 
 If a list of these constants is used, all of these participation types
-will be selected:
+will be selected.
 
     >>> for question in foo_bar.searchQuestions(
-    ...         participation=[
-    ...             QuestionParticipation.OWNER,
-    ...             QuestionParticipation.ANSWERER],
+    ...         participation=(QuestionParticipation.OWNER,
+    ...                        QuestionParticipation.ANSWERER),
     ...         status=None):
     ...     print question.title
     mailto: problem in webpage
@@ -145,40 +150,41 @@
     Firefox is slow and consumes too much RAM
 
 
-=== language ===
-
-By default, questions in all languages are included in the results.
-It is possible to filter questions by the language they were written
-in . One or a list of ILanguage object should be passed in the
-language parameter to specify the language filter.
-
-    >>> from canonical.launchpad.interfaces import ILanguageSet
+Language
+--------
+
+By default, questions in all languages are included in the results.  It is
+possible to filter questions by the language they were written in.  One or a
+sequence of ILanguage object can be passed in to specify the language filter.
+
+    >>> from lp.services.worlddata.interfaces.language import ILanguageSet
     >>> spanish = getUtility(ILanguageSet)['es']
     >>> english = getUtility(ILanguageSet)['en']
 
 Foo bar doesn't have any questions written in Spanish.
 
-    >>> for question in foo_bar.searchQuestions(language=spanish):
-    ...     print question.title
-
-But carlos has one.
-
+    >>> list(foo_bar.searchQuestions(language=spanish))
+    []
+
+But Carlos has one.
+
+    # Because not everyone uses a real editor <wink>
+    >>> from canonical.encoding import ascii_smash
     >>> carlos_raw = personset.getByName('carlos')
     >>> carlos = IQuestionsPerson(carlos_raw)
     >>> for question in carlos.searchQuestions(
-    ...     language=[english, spanish]):
-    ...     [question.title, question.language.code]
-    [u'Problema al recompilar kernel con soporte smp (doble-n\xfacleo)',
-     u'es']
-
-
-=== needs_attention ===
-
-The method accept a parameter called needs_attention which only selects
-the questions that needs attention from the person. This includes questions
-owned by the person in the ANSWERED or NEEDSINFO state. It also includes
-questions on which the person requested for more information or gave an
-answer and that are back in the OPEN state.
+    ...         language=(english, spanish)):
+    ...     print ascii_smash(question.title), question.language.code
+    Problema al recompilar kernel con soporte smp (doble-nucleo)    es
+
+
+Questions needing attention
+---------------------------
+
+You can select only the questions that needs attention from a person.  This
+includes questions owned by the person in the ANSWERED or NEEDSINFO state.  It
+also includes questions on which the person requested more information or gave
+an answer and are back in the OPEN state.
 
     >>> for question in foo_bar.searchQuestions(needs_attention=True):
     ...     print question.status.title, question.owner.displayname, (
@@ -187,70 +193,80 @@
     Needs information Foo Bar       Slow system
 
 
-=== Combination ===
+Search combinations
+-------------------
 
-The returned sets of questions is the intersection of the sets delimited
-by each criteria:
+The results are the intersection of the sets delimited by each criteria.
 
     >>> for question in foo_bar.searchQuestions(
-    ...         search_text='firefox OR Java', status=QuestionStatus.ANSWERED,
+    ...         search_text='firefox OR Java',
+    ...         status=QuestionStatus.ANSWERED,
     ...         participation=QuestionParticipation.COMMENTER):
     ...     print question.title, question.status.title
     Installation of Java Runtime Environment for Mozilla    Answered
     Newly installed plug-in doesn't seem to be used         Answered
 
 
-== getQuestionLanguages() ==
+Question languages
+==================
 
 IQuestionsPerson also defines a getQuestionLanguages() attribute which
 contains the set of languages used by all of the questions in which this
 person is involved.
 
-    >>> sorted(language.code for language in foo_bar.getQuestionLanguages())
-    [u'en']
-
-This includes questions which the person owns. But also, questions that
-the user subscribed to.
-
-    >>> from canonical.launchpad.interfaces import IQuestionSet
+    >>> print ', '.join(
+    ...     sorted(language.code
+    ...            for language in foo_bar.getQuestionLanguages()))
+    en
+
+This includes questions which the person owns, and questions that the user is
+subscribed to...
+
+    >>> from lp.answers.interfaces.questioncollection import IQuestionSet
     >>> pt_BR_question = getUtility(IQuestionSet).get(13)
     >>> login('[e-mail]')
     >>> pt_BR_question.subscribe(foo_bar_raw)
     <QuestionSubscription...>
 
-    >>> sorted(language.code for language in foo_bar.getQuestionLanguages())
-    [u'en', u'pt_BR']
+    >>> print ', '.join(
+    ...     sorted(language.code
+    ...            for language in foo_bar.getQuestionLanguages()))
+    en, pt_BR
 
-And also questions for which he's the answerer.
+...and questions for which he's the answerer...
 
     >>> es_question = getUtility(IQuestionSet).get(12)
     >>> es_question.reject(foo_bar_raw, 'Reject question.')
     <QuestionMessage...>
 
-    >>> sorted(language.code for language in foo_bar.getQuestionLanguages())
-    [u'en', u'es', u'pt_BR']
+    >>> print ', '.join(
+    ...     sorted(language.code
+    ...            for language in foo_bar.getQuestionLanguages()))
+    en, es, pt_BR
 
-As well, as question which are assigned to the user.
+...as well as questions which are assigned to the user...
 
     >>> pt_BR_question.assignee = carlos_raw
-    >>> from canonical.database.sqlbase import flush_database_updates
-    >>> flush_database_updates()
-
-    >>> sorted(language.code for language in carlos.getQuestionLanguages())
-    [u'es', u'pt_BR']
-
-And questions on which the user commented:
+    >>> print ', '.join(
+    ...     sorted(language.code
+    ...            for language in carlos.getQuestionLanguages()))
+    es, pt_BR
+
+...and questions on which the user commented.
 
     >>> en_question = getUtility(IQuestionSet).get(1)
     >>> login('[e-mail]')
     >>> en_question.addComment(carlos_raw, 'A simple comment.')
     <QuestionMessage...>
 
-    >>> sorted(language.code for language in carlos.getQuestionLanguages())
-    [u'en', u'es', u'pt_BR']
-
-
-== getDirectAnswerQuestionTargets() ==
+    >>> print ', '.join(
+    ...     sorted(language.code
+    ...            for language in carlos.getQuestionLanguages()))
+    en, es, pt_BR
+
+
+Direct subscriptions
+====================
 
 IQuestionsPerson defines getDirectAnswerQuestionTargets that can be used to
 retrieve a list of IQuestionTargets that a person subscribed himself to as an
@@ -261,9 +277,10 @@
     >>> no_priv.getDirectAnswerQuestionTargets()
     []
 
-    >>> from canonical.launchpad.interfaces import IProductSet
+    >>> from lp.registry.interfaces.product import IProductSet
     >>> firefox = getUtility(IProductSet).getByName("firefox")
-    >>> # Answer contacts must speak a language
+
+    # Answer contacts must speak a language
     >>> no_priv_raw.addLanguage(english)
     >>> firefox.addAnswerContact(no_priv_raw)
     True
@@ -272,7 +289,9 @@
     ...    print target.name
     firefox
 
-== getTeamAnswerQuestionTargets() ==
+
+Indirect subscriptions
+======================
 
 IQuestionsPerson defines getTeamAnswerQuestionTargets that retrieves a list of
 IQuestionTargets that the person is subscribed to indirectly as an answer
@@ -283,20 +302,21 @@
     >>> no_priv_raw.inTeam(landscape_team)
     True
 
-    >>> from canonical.launchpad.interfaces import IDistributionSet
+    >>> from lp.registry.interfaces.distribution import IDistributionSet
     >>> ubuntu = getUtility(IDistributionSet).getByName("ubuntu")
     >>> landscape_team.addLanguage(english)
     >>> ubuntu.addAnswerContact(landscape_team)
     True
 
-    >>> sorted(target.name
-    ...        for target in no_priv.getTeamAnswerQuestionTargets())
-    [u'ubuntu']
+    >>> print ', '.join(
+    ...     sorted(target.name
+    ...            for target in no_priv.getTeamAnswerQuestionTargets()))
+    ubuntu
 
-Indirect team membership is also taken in consideration. For example,
-the Landscape Team joins the Translator Team. So targets for which the
-Translator team is an answer contact will be included in No Privileges
-Person's supported IQuestionTargets:
+Indirect team membership is also taken in consideration.  For example, when
+the Landscape Team joins the Translator Team, targets for which the Translator
+team is an answer contact will be included in No Privileges Person's supported
+IQuestionTargets.
 
     >>> translator_team = personset.getByName('ubuntu-translators')
     >>> no_priv_raw.inTeam(translator_team)
@@ -315,36 +335,33 @@
     >>> translator_team.addLanguage(english)
     >>> evolution_package.addAnswerContact(translator_team)
     True
-    >>> sorted(target.name
-    ...        for target in no_priv.getTeamAnswerQuestionTargets())
-    [u'evolution', u'ubuntu']
-
-
-== Deactivated pillars and *AnswerQuestionTargets() ==
-
-getDirectAnswerQuestionTargets() and getTeamAnswerQuestionTargets() use
-a _getQuestionTargetsFromAnswerContacts() to build a distinct list of
-valid IQuestionTargets. It ensures that no deactivated pillars are in
-the list.
+    >>> print ', '.join(
+    ...     sorted(target.name
+    ...            for target in no_priv.getTeamAnswerQuestionTargets()))
+    evolution, ubuntu
+
+
+Deactivated pillars
+===================
+
+Only valid IQuestionTargets are returned, ensuring that no deactivated pillars
+are in the results.
 
 If the Firefox project is deactivated, it is removed from the list of
 supported projects.
 
-    >>> from canonical.launchpad.ftests import syncUpdate
-
     >>> login('[e-mail]')
     >>> firefox.active = False
-    >>> syncUpdate(firefox)
     >>> sorted(target.name
     ...        for target in no_priv.getDirectAnswerQuestionTargets())
     []
 
-When the Firefox project is reactivated, the answer contact relationship
-is visible. It is important to preserve the continuity of the project in
-cases were we only want is deactivated for a short period.
+When the Firefox project is reactivated, the answer contact relationship is
+visible.  These relationships are persistent for cases where we only want is
+deactivated for a short period.
 
     >>> firefox.active = True
-    >>> syncUpdate(firefox)
-    >>> sorted(target.name
-    ...        for target in no_priv.getDirectAnswerQuestionTargets())
-    [u'firefox']
+    >>> print ', '.join(
+    ...     sorted(target.name
+    ...            for target in no_priv.getDirectAnswerQuestionTargets()))
+    firefox

=== renamed file 'lib/lp/answers/doc/project.txt' => 'lib/lp/answers/doc/projectgroup.txt'
--- lib/lp/answers/doc/project.txt	2009-03-24 12:43:49 +0000
+++ lib/lp/answers/doc/projectgroup.txt	2010-02-10 15:24:19 +0000
@@ -1,12 +1,15 @@
-= Project and the Answer Tracker =
+===============================
+Projects and the answer tracker
+===============================
 
-Although question cannot be filed directly against projects, IProject in
-Launchpad also provides the IQuestionCollection and
+Although questions cannot be filed directly against project groups (nee
+'Project'), IProject provides the IQuestionCollection and
 ISearchableByQuestionOwner interfaces.
 
     >>> from canonical.launchpad.webapp.testing import verifyObject
-    >>> from canonical.launchpad.interfaces import (
-    ...     IProjectSet, ISearchableByQuestionOwner, IQuestionCollection)
+    >>> from lp.registry.interfaces.project import IProjectSet
+    >>> from lp.answers.interfaces.questioncollection import (
+    ...     ISearchableByQuestionOwner, IQuestionCollection)
 
     >>> mozilla_project = getUtility(IProjectSet).getByName('mozilla')
     >>> verifyObject(IQuestionCollection, mozilla_project)
@@ -14,37 +17,41 @@
     >>> verifyObject(ISearchableByQuestionOwner, mozilla_project)
     True
 
-== searchQuestions() ==
-
-This means that it is possible to search for all questions filed against
-products in a project using the project searchQuestions() method.
-
-    # Add a question to thunderbird.
-    >>> from canonical.launchpad.interfaces import ILaunchBag, IProductSet
+
+Questions filed against project in a project group
+==================================================
+
+You can search for all questions filed against projects in a project using the
+project group's searchQuestions() method.
+
+    >>> from lp.registry.interfaces.person import IPersonSet
+    >>> from lp.registry.interfaces.product import IProductSet
+
     >>> login('[e-mail]')
     >>> thunderbird = getUtility(IProductSet).getByName('thunderbird')
-    >>> sample_person = getUtility(ILaunchBag).user
+    >>> sample_person = getUtility(IPersonSet).getByName('name12')
     >>> question = thunderbird.newQuestion(
-    ...     sample_person, "SVG attachments aren't displayed",
+    ...     sample_person,
+    ...     "SVG attachments aren't displayed ",
     ...     "It would be a nice feature if SVG attachments could be displayed"
-    ...     "inlined.")
+    ...     " inlined.")
 
     >>> for question in mozilla_project.searchQuestions(search_text='svg'):
     ...     print question.title, question.target.displayname
     SVG attachments aren't displayed            Mozilla Thunderbird
     Problem showing the SVG demo on W3C site    Mozilla Firefox
 
-In the case were a Project has no Products, then we can expect no 
-possible questions.
+In the case where a project group has no projects, there are no results.
 
     >>> aaa_project = getUtility(IProjectSet).getByName('aaa')
-    >>> [q for question in aaa_project.searchQuestions()]
+    >>> list(aaa_project.searchQuestions())
     []
 
-Questions can be searched by all the standard searchQuestions() parameters
-(consult questiontarget.txt for the full details.)
+Questions can be searched by all the standard searchQuestions() parameters.
+See questiontarget.txt for the full details.
 
-    >>> from canonical.launchpad.interfaces import QuestionStatus, QuestionSort
+    >>> from lp.answers.interfaces.questionenums import (
+    ...     QuestionSort, QuestionStatus)
     >>> for question in mozilla_project.searchQuestions(
     ...     owner=sample_person, status=QuestionStatus.OPEN,
     ...     sort=QuestionSort.OLDEST_FIRST):
@@ -52,20 +59,21 @@
     Problem showing the SVG demo on W3C site    Mozilla Firefox
     SVG attachments aren't displayed            Mozilla Thunderbird
 
-== getQuestionLanguages() ==
-
-The getQuestionLanguages() returns the set of languages that is used by
-all the questions in the project products.
-
-    >>> sorted(language.code
-    ...        for language in mozilla_project.getQuestionLanguages())
-    [u'en', u'pt_BR']
-
-(The firefox product has one question created in Brazilian Portuguese.)
-
-In the case where a Project has no Products, language questions will 
-still return and empty set.
-
-    >>> [language.code for language in aaa_project.getQuestionLanguages()]
+
+Languages
+=========
+
+getQuestionLanguages() returns the set of languages that is used by all the
+questions in the project group's projects.
+
+    # The Firefox project group has one question created in Brazilian
+    # Portuguese. 
+    >>> print ', '.join(
+    ...     sorted(language.code
+    ...            for language in mozilla_project.getQuestionLanguages()))
+    en, pt_BR
+
+In the case where a project group has no projects, there are no results.
+
+    >>> list(aaa_project.getQuestionLanguages())
     []
-

=== modified file 'lib/lp/answers/doc/question.txt'
--- lib/lp/answers/doc/question.txt	2009-03-24 12:43:49 +0000
+++ lib/lp/answers/doc/question.txt	2010-02-10 15:24:19 +0000
@@ -1,21 +1,24 @@
-= Launchpad Answer Tracker =
+========================
+Launchpad Answer Tracker
+========================
 
-Launchpad includes an Answer Tracker where users can post questions
-(usually about problems they encounter with projects) and other can
-answer them.) Questions are created and accessed using the
-IQuestionTarget interface. This interface is available on Products,
-Distributions and DistributionSourcePackages.
+Launchpad includes an Answer Tracker where users can post questions, usually
+about problems they encounter with projects, and other people can answer them.
+Questions are created and accessed using the IQuestionTarget interface.  This
+interface is available on Products, Distributions and
+DistributionSourcePackages.
 
     >>> login('[e-mail]')
 
     >>> from canonical.launchpad.webapp.testing import verifyObject
-    >>> from canonical.launchpad.interfaces import (
-    ...     IDistributionSet, IProductSet, IPersonSet, IQuestionTarget)
+    >>> from lp.answers.interfaces.questiontarget import IQuestionTarget
+    >>> from lp.registry.interfaces.product import IProductSet
 
     >>> firefox = getUtility(IProductSet)['firefox']
     >>> verifyObject(IQuestionTarget, firefox)
     True
 
+    >>> from lp.registry.interfaces.distribution import IDistributionSet
     >>> ubuntu = getUtility(IDistributionSet).getByName('ubuntu')
     >>> verifyObject(IQuestionTarget, ubuntu)
     True
@@ -24,9 +27,9 @@
     >>> verifyObject(IQuestionTarget, evolution_in_ubuntu)
     True
 
-Although Distribution series do not implement the IQuestionTarget
-interface, it is possible to adapt one to it. (The adapter is actually
-the distroseries's distribution.)
+Although distribution series do not implement the IQuestionTarget interface,
+it is possible to adapt one to it.  The adapter is actually the distroseries's
+distribution.
 
     >>> ubuntu_warty = ubuntu.getSeries('warty')
     >>> IQuestionTarget.providedBy(ubuntu_warty)
@@ -56,29 +59,33 @@
 You create a new question by calling the newQuestion() method of an
 IQuestionTarget attribute.
 
+    >>> from lp.registry.interfaces.person import IPersonSet
     >>> sample_person = getUtility(IPersonSet).getByEmail('[e-mail]')
     >>> firefox_question = firefox.newQuestion(
     ...     sample_person, "Firefox question", "Unable to use Firefox")
 
-(The complete IQuestionTarget interface is documented in
-../interfaces/ftests/questiontarget.txt.)
-
-== Official usage ==
-
-A product or distribution may be offically supported by the community
-using the Answer Tracker. This status is set by the official_answers
-attribute on the IProduct and IDistribution.
+The complete IQuestionTarget interface is documented in questiontarget.txt.
+
+
+Official usage
+==============
+
+A product or distribution may be officially supported by the community using
+the Answer Tracker.  This status is set by the official_answers attribute on
+the IProduct and IDistribution.
 
     >>> ubuntu.official_answers
     True
     >>> firefox.official_answers
     True
 
-== IQuestion ==
-
-Questions are manipulated through the IQuestion interface:
-
-    >>> from canonical.launchpad.interfaces import IQuestion
+
+IQuestion interface
+===================
+
+Questions are manipulated through the IQuestion interface.
+
+    >>> from lp.answers.interfaces.question import IQuestion
     >>> from zope.security.proxy import removeSecurityProxy
 
     # The complete interface is not necessarily available to the
@@ -88,21 +95,27 @@
 
 The person who submitted the question is available in the owner field.
 
-    >>> firefox_question.owner == sample_person
-    True
+    >>> firefox_question.owner
+    <Person at ... name12 (Sample Person)>
 
 When the question is created, the owner is added to the question's
-subscribers:
-
-    >>> sample_person in [s.person for s in firefox_question.subscriptions]
-    True
-
-The question status is 'Open':
-
-    >>> firefox_question.status.title
-    'Open'
-
-And the creation time is recorded in the datecreated attribute:
+subscribers.
+
+    >>> from operator import attrgetter
+    >>> def print_subscribers(question):
+    ...     people = [subscription.person
+    ...               for subscription in question.subscriptions]
+    ...     for person in sorted(people, key=attrgetter('name')):
+    ...         print person.displayname
+    >>> print_subscribers(firefox_question)
+    Sample Person
+
+The question status is 'Open'.
+
+    >>> print firefox_question.status.title
+    Open
+
+The question has a creation time.
 
     >>> from datetime import datetime, timedelta
     >>> from pytz import UTC
@@ -110,11 +123,10 @@
     >>> now - firefox_question.datecreated < timedelta(seconds=5)
     True
 
-The target onto which the question was created is available through the
-'target' attribute:
+The target onto which the question was created is also available.
 
-    >>> firefox_question.target == firefox
-    True
+    >>> print firefox_question.target.displayname
+    Mozilla Firefox
 
 It is also possible to adapt a question to its IQuestionTarget.
 
@@ -163,66 +175,69 @@
     firefox
 
 
-== Subscriptions and Notifications ==
+Subscriptions and notifications
+===============================
 
 Whenever a question is created or changed, email notifications will be
-sent. To receive such notification, one can subscribe to the bug using
+sent.  To receive such notification, one can subscribe to the bug using
 the subscribe() method.
 
     >>> no_priv = getUtility(IPersonSet).getByName('no-priv')
     >>> subscription = firefox_question.subscribe(no_priv)
 
-The list of subscriptions is available in the subscriptions attribute.
-In the current case, the subscribers will include the owner
-('Sample Person') and the newly subscribed person.
+The subscribers include the owner and the newly subscribed person.
 
-    >>> [s.person.displayname for s in firefox_question.subscriptions]
-    [u'Sample Person', u'No Privileges Person']
+    >>> print_subscribers(firefox_question)
+    Sample Person
+    No Privileges Person
 
 The getDirectSubscribers() method returns a sorted list of subscribers.
 This method iterates like the NotificationRecipientSet returned by the
 getDirectRecipients() method.
 
-    >>> [person.displayname
-    ...  for person in firefox_question.getDirectSubscribers()]
-    [u'No Privileges Person', u'Sample Person']
+    >>> for person in firefox_question.getDirectSubscribers():
+    ...     print person.displayname
+    No Privileges Person
+    Sample Person
 
 To remove a person from the subscriptions list, we use the unsubscribe()
 method.
 
     >>> firefox_question.unsubscribe(no_priv)
-    >>> [s.person.displayname for s in firefox_question.subscriptions]
-    [u'Sample Person']
+    >>> print_subscribers(firefox_question)
+    Sample Person
 
-The persons who are on the subscription list are said to be directly
-subscribed to the question. They explicitly choose to get notifications
-about that particular question. This list of persons is available through
-the getDirectRecipients() method.
+The people on the subscription list are said to be directly subscribed to the
+question.  They explicitly chose to get notifications about that particular
+question.  This list of people is available through the getDirectRecipients()
+method.
 
     >>> subscribers = firefox_question.getDirectRecipients()
 
 That method returns an INotificationRecipientSet, containing the direct
-subscribers along the rationale for contacting them:
+subscribers along with the rationale for contacting them.
 
     >>> from canonical.launchpad.interfaces import INotificationRecipientSet
     >>> verifyObject(INotificationRecipientSet, subscribers)
     True
-    >>> [person.displayname for person in subscribers]
-    [u'Sample Person']
-    >>> subscribers.getReason(sample_person)
-    ('You received this question notification because you are a direct
-      subscriber of the question.', 'Subscriber')
+    >>> def print_reason(subscribers):
+    ...     for person in subscribers:
+    ...         text, header = subscribers.getReason(person)
+    ...         print header, person.displayname, text
+    >>> print_reason(subscribers)
+    Subscriber Sample Person You received this question notification
+    because you are a direct subscriber of the question.
 
-There is also a list of 'indirect' subscribers to the question. These
-are persons that didn't explicitly subscribed to the question, but that
-will receive notifications for other reason. Answer contacts for the
-question target are part of the indirect subscribers list.
+There is also a list of 'indirect' subscribers to the question.  These are
+people that didn't explicitly subscribe to the question, but that will receive
+notifications for other reasons.  Answer contacts for the question target are
+part of the indirect subscribers list.
 
     # There are no answer contacts on the firefox product.
-    >>> [person.displayname
-    ...     for person in firefox_question.getIndirectRecipients()]
+    >>> list(firefox_question.getIndirectRecipients())
     []
-    >>> from canonical.launchpad.interfaces import ILanguageSet
+
+    >>> from lp.services.worlddata.interfaces.language import ILanguageSet
     >>> english = getUtility(ILanguageSet)['en']
     >>> no_priv.addLanguage(english)
     >>> firefox.addAnswerContact(no_priv)
@@ -231,16 +246,14 @@
     >>> indirect_subscribers = firefox_question.getIndirectRecipients()
     >>> verifyObject(INotificationRecipientSet, indirect_subscribers)
     True
-    >>> [person.displayname for person in indirect_subscribers]
-    [u'No Privileges Person']
-    >>> indirect_subscribers.getReason(no_priv)
-    (u'You received this question notification because you are an answer
-      contact for Mozilla Firefox.',
-     u'Answer Contact (Mozilla Firefox)')
+    >>> print_reason(indirect_subscribers)
+    Answer Contact (Mozilla Firefox) No Privileges Person
+    You received this question notification because you are an answer
+    contact for Mozilla Firefox.
 
-There is a special case for when the question's is associated to a
-source package. The answer contacts for both the distribution and the
-source package are part of the indirect subscribers list.
+There is a special case for when the question is associated with a source
+package.  The answer contacts for both the distribution and the source package
+are part of the indirect subscribers list.
 
     # Let's register some answer contacts for the distribution and
     # the package.
@@ -257,64 +270,80 @@
     >>> package_question = evolution_in_ubuntu.newQuestion(
     ...     sample_person, 'Upgrading to Evolution 1.4 breaks plug-ins',
     ...     "The FnordsHighlighter plug-in doesn't work after upgrade.")
-    >>> [s.person.displayname for s in package_question.subscriptions]
-    [u'Sample Person']
+
+    >>> print_subscribers(package_question)
+    Sample Person
+
     >>> indirect_subscribers = package_question.getIndirectRecipients()
-    >>> [person.displayname for person in indirect_subscribers]
-    [u'No Privileges Person', u'Ubuntu Team']
-    >>> indirect_subscribers.getReason(ubuntu_team)
-    (u'You received this question notification because you are a member of
-      Ubuntu Team, which is an answer contact for Ubuntu.',
-     u'Answer Contact (ubuntu) @ubuntu-team')
-    >>> indirect_subscribers.getReason(no_priv)
-    (u'You received this question notification because you are an answer
-      contact for evolution in ubuntu.',
-     u'Answer Contact (evolution in ubuntu)')
+    >>> for person in indirect_subscribers:
+    ...     print person.displayname
+    No Privileges Person
+    Ubuntu Team
+
+    >>> text, header = indirect_subscribers.getReason(ubuntu_team)
+    >>> print header, text
+    Answer Contact (ubuntu) @ubuntu-team
+    You received this question notification because you are a member of
+    Ubuntu Team, which is an answer contact for Ubuntu.
 
 The question's assignee is also part of the indirect subscription list:
 
-    >>> login('[e-mail]')
+    >>> login('[e-mail]')
     >>> package_question.assignee = getUtility(IPersonSet).getByName('name16')
     >>> indirect_subscribers = package_question.getIndirectRecipients()
-    >>> [person.displayname for person in indirect_subscribers]
-    [u'Foo Bar', u'No Privileges Person', u'Ubuntu Team']
-    >>> indirect_subscribers.getReason(package_question.assignee)
-    ('You received this question notification because you are the assignee
-      for this question.',
-     'Assignee')
+    >>> for person in indirect_subscribers:
+    ...     print person.displayname
+    Foo Bar
+    No Privileges Person
+    Ubuntu Team
+
+    >>> text, header = indirect_subscribers.getReason(
+    ...     package_question.assignee)
+    >>> print header, text
+    Assignee
+    You received this question notification because you are the assignee for
+    this question.
 
 The getIndirectSubscribers() method iterates like the getIndirectRecipients()
 method, but it returns a sorted list instead of a NotificationRecipientSet.
 It too contains the question assignee.
 
     >>> indirect_subscribers = package_question.getIndirectSubscribers()
-    >>> [person.displayname for person in indirect_subscribers]
-    [u'Foo Bar', u'No Privileges Person', u'Ubuntu Team']
+    >>> for person in indirect_subscribers:
+    ...     print person.displayname
+    Foo Bar
+    No Privileges Person
+    Ubuntu Team
 
-Notifications are sent to the list of direct and indirect subscribers.
-The notification recipients list can be obtained by using the
-getRecipients() method.
+Notifications are sent to the list of direct and indirect subscribers.  The
+notification recipients list can be obtained by using the getRecipients()
+method.
 
     >>> login('[e-mail]')
     >>> subscribers = firefox_question.getRecipients()
     >>> verifyObject(INotificationRecipientSet, subscribers)
     True
-    >>> [person.displayname for person in subscribers]
-    [u'No Privileges Person', u'Sample Person']
-
-(More documentation on the question notifications can be found in
-'answer-tracker-notifications.txt'.)
-
-
-== Workflow ==
+    >>> for person in subscribers:
+    ...     print person.displayname
+    No Privileges Person
+    Sample Person
+
+More documentation on the question notifications can be found in
+`answer-tracker-notifications.txt`.
+
+
+Workflow
+========
 
 A question status should not be manipulated directly but through the
 workflow methods.
 
 The complete question workflow is documented in
-'answer-tracker-workflow.txt'.
-
-== Bug Linking ==
+`answer-tracker-workflow.txt`.
+
+
+Bug linking
+===========
 
 Question implements the IBugLinkTarget interface which makes it possible
 to link bug report to question.
@@ -323,13 +352,13 @@
     >>> verifyObject(IBugLinkTarget, firefox_question)
     True
 
-(See ../interfaces/ftests/buglinktarget.txt for the documentation and
-test of the IBugLinkTarget interface.)
-
-When a bug is linked to a question, the question's owner is subscribed to
-the bug.
-
-    >>> from canonical.launchpad.interfaces import IBugSet
+See ../../bugs/tests/buglinktarget.txt for the documentation and test of the
+IBugLinkTarget interface.
+
+When a bug is linked to a question, the question's owner is subscribed to the
+bug.
+
+    >>> from lp.bugs.interfaces.bug import IBugSet
     >>> bug7 = getUtility(IBugSet).get(7)
     >>> bug7.isSubscribed(firefox_question.owner)
     False
@@ -338,33 +367,34 @@
     >>> bug7.isSubscribed(firefox_question.owner)
     True
 
-When the link is removed, the owner is unsubscribed:
+When the link is removed, the owner is unsubscribed.
 
     >>> firefox_question.unlinkBug(bug7)
     <QuestionBug...>
     >>> bug7.isSubscribed(firefox_question.owner)
     False
 
-== Unsupported Questions ==
-
-While a Person may ask questions in his language of choice, that does
-not mean that indirect subscribers (Answer Contacts) to an
-IQuestionTarget speak that language. IQuestionTarget can return a list
-Questions in languages that are not supported
+
+Unsupported questions
+=====================
+
+While a Person may ask questions in his language of choice, that does not mean
+that indirect subscribers (Answer Contacts) to an IQuestionTarget speak that
+language.  IQuestionTarget can return a list Questions in languages that are
+not supported.
 
     >>> unsupported_questions = firefox.searchQuestions(unsupported=True)
-    >>> sorted([question.title for question in unsupported_questions])
+    >>> sorted(question.title for question in unsupported_questions)
     [u'Problemas de Impress\xe3o no Firefox']
 
     >>> unsupported_questions = evolution_in_ubuntu.searchQuestions(
     ...     unsupported=True)
-    >>> sorted([question.title for question in unsupported_questions])
+    >>> sorted(question.title for question in unsupported_questions)
     []
 
     >>> warty_question_target = IQuestionTarget(ubuntu_warty)
     >>> unsupported_questions = warty_question_target.searchQuestions(
     ...     unsupported=True)
-    >>> sorted([question.title for question in unsupported_questions])
+    >>> sorted(question.title for question in unsupported_questions)
     [u'Problema al recompilar kernel con soporte smp (doble-n\xfacleo)',
      u'\u0639\u0643\u0633 \u0627\u0644\u062a\u063a\u064a\u064a\u0631...]
-

=== renamed file 'lib/lp/answers/doc/utility.txt' => 'lib/lp/answers/doc/questionsets.txt'
--- lib/lp/answers/doc/utility.txt	2009-03-24 12:43:49 +0000
+++ lib/lp/answers/doc/questionsets.txt	2010-02-10 15:24:19 +0000
@@ -1,69 +1,75 @@
-= Answer Tracker Utility: IQuestionSet =
+====================
+Question collections
+====================
 
-There is an IQuestionSet utility that can be use to retrieve and search
-for question whatever the target they were created in.
+The IQuestionSet utility is used to retrieve and search for questions no
+matter which question target they were created for.
 
     >>> from canonical.launchpad.webapp.testing import verifyObject
-    >>> from canonical.launchpad.interfaces import IQuestionSet
+    >>> from lp.answers.interfaces.questioncollection import IQuestionSet
     >>> question_set = getUtility(IQuestionSet)
     >>> verifyObject(IQuestionSet, question_set)
     True
 
 
-== get() ==
+Retrieving questions
+====================
 
-The get() method can be used to get a question with a specific id:
+The get() method can be used to retrieve a question with a specific id.
 
     >>> question_one = question_set.get(1)
-    >>> question_one.title
-    u'Firefox cannot render Bank Site'
+    >>> print question_one.title
+    Firefox cannot render Bank Site
 
-If no question exists, a default value is returned:
+If no question exists, a default value is returned.
 
     >>> default = object()
     >>> question_nonexistant = question_set.get(123456, default=default)
     >>> question_nonexistant is default
     True
 
-If no default value is given, None is returned:
-
-    >>> question_set.get(123456) is None
-    True
-
-
-== searchQuestions() ==
-
-IQuestionSet also defines a searchQuestions() method that can be used to
-search for questions defined in any products or distributions (in fact,
-in any context that allows questions to be defined). Two search criteria
-are defined search_text and status.
-
-
-=== search_text ===
-
-The search_text parameter will limit the questions to those matching
-the query using the regular full text algorithm.
-
+If no default value is given, None is returned.
+
+    >>> print question_set.get(123456)
+    None
+
+
+Searching questions
+===================
+
+The IQuestionSet interface defines a searchQuestions() method that is used to
+search for questions defined in any question target.
+
+
+Search text
+-----------
+
+The search_text parameter will return questions matching the query using the
+regular full text algorithm.
+
+    # Because not everyone uses a real editor <wink>
+    >>> from canonical.encoding import ascii_smash
     >>> for question in question_set.searchQuestions(search_text='firefox'):
-    ...     print repr(question.title), question.target.displayname
-    u'Problemas de Impress\xe3o no Firefox'        Mozilla Firefox
-    u'Firefox loses focus and gets stuck'          Mozilla Firefox
-    u'Firefox cannot render Bank Site'             Mozilla Firefox
-    u'mailto: problem in webpage'                  mozilla-firefox in ubuntu
-    u"Newly installed plug-in doesn't seem to be used" Mozilla Firefox
-    u'Problem showing the SVG demo on W3C site'    Mozilla Firefox
-    u'\u0639\u0643\u0633 ...'                      Ubuntu
-
-
-=== status ===
-
-By default, expired and invalid questions are not searched for. The
-status parameter can be used to select the questions in the status
-you are interested in.
-
-    >>> from canonical.launchpad.interfaces import QuestionStatus
+    ...     print ascii_smash(question.title), question.target.displayname
+    Problemas de Impressao no Firefox                   Mozilla Firefox
+    Firefox loses focus and gets stuck                  Mozilla Firefox
+    Firefox cannot render Bank Site                     Mozilla Firefox
+    mailto: problem in webpage                        mozilla-firefox in ubuntu
+    Newly installed plug-in doesn't seem to be used     Mozilla Firefox
+    Problem showing the SVG demo on W3C site            Mozilla Firefox
+    AINKAFSEEN ALEFLAMTEHGHAINYEHYEHREHALEFTEH ...      Ubuntu
+
+
+Status
+------
+
+By default, expired and invalid questions are not searched for.  The status
+parameter can be used to select the questions in the status you are interested
+in.
+
+    >>> from lp.answers.interfaces.questionenums import QuestionStatus
     >>> for question in question_set.searchQuestions(
-    ...     status=QuestionStatus.INVALID):
+    ...         status=QuestionStatus.INVALID):
     ...     print question.title, question.status.title, (
     ...         question.target.displayname)
     Firefox is slow and consumes too much RAM Invalid mozilla-firefox in ubuntu
@@ -78,111 +84,118 @@
     Firefox is slow and consumes too much RAM Invalid mozilla-firefox in ubuntu
 
 
-=== language ===
+Language
+--------
 
 The language parameter can be used to select only questions written in a
 particular language.
 
-    >>> from canonical.launchpad.interfaces import ILanguageSet
+    >>> from lp.services.worlddata.interfaces.language import ILanguageSet
     >>> spanish = getUtility(ILanguageSet)['es']
     >>> for t in question_set.searchQuestions(language=spanish):
-    ...     print t.title.encode('us-ascii', 'backslashreplace')
-    Problema al recompilar kernel con soporte smp (doble-n\xfacleo)
-
-=== Combination ===
-
-The returned sets of questions is the intersection of the sets delimited
-by each criteria:
+    ...     print ascii_smash(t.title)
+    Problema al recompilar kernel con soporte smp (doble-nucleo)
+
+
+Combinations
+------------
+
+The returned set of questions is the intersection of the sets delimited by
+each criteria.
 
     >>> for question in question_set.searchQuestions(
     ...         search_text='firefox',
-    ...         status=[QuestionStatus.OPEN, QuestionStatus.INVALID]):
-    ...     print repr(question.title), question.status.title, (
+    ...         status=(QuestionStatus.OPEN, QuestionStatus.INVALID)):
+    ...     print ascii_smash(question.title), question.status.title, (
     ...           question.target.displayname)
-    u'Problemas de Impress\xe3o no Firefox'     Open    Mozilla Firefox
-    u'Firefox is slow and consumes too much RAM' Invalid mozilla-firefox in ubuntu
-    u'Firefox loses focus and gets stuck'       Open    Mozilla Firefox
-    u'Firefox cannot render Bank Site'          Open    Mozilla Firefox
-    u'Problem showing the SVG demo on W3C site' Open    Mozilla Firefox
-    u'\u0639\u0643\u0633 ...'                   Open    Ubuntu
-
-
-=== Sort Order ===
-
-When using the search_text criteria, the default is to sort the results
-by relevancy. One can use the sort parameter to change that. It takes
-one of the constant defined in the QuestionSort enumeration.
-
-    >>> from canonical.launchpad.interfaces import QuestionSort
+    Problemas de Impressao no Firefox Open              Mozilla Firefox
+    Firefox is slow and consumes too much RAM Invalid mozilla-firefox in ubuntu
+    Firefox loses focus and gets stuck Open             Mozilla Firefox
+    Firefox cannot render Bank Site Open                Mozilla Firefox
+    Problem showing the SVG demo on W3C site Open       Mozilla Firefox
+    AINKAFSEEN ALEFLAMTEHGHAINYEHYEHREHALEFTEH ...      Ubuntu
+
+
+Sort order
+----------
+
+When using the search_text criteria, the default is to sort the results by
+relevancy.  One can use the sort parameter to change the order.  It takes one
+of the constant defined in the QuestionSort enumeration.
+
+    >>> from lp.answers.interfaces.questionenums import QuestionSort
     >>> for question in question_set.searchQuestions(
     ...         search_text='firefox', sort=QuestionSort.OLDEST_FIRST):
-    ...     print question.id, repr(question.title), (
+    ...     print question.id, ascii_smash(question.title), (
     ...          question.target.displayname)
-    14 u'\u0639\u0643\u0633 ...'                   Ubuntu
-    1 u'Firefox cannot render Bank Site'           Mozilla Firefox
-    2 u'Problem showing the SVG demo on W3C site'  Mozilla Firefox
-    4 u'Firefox loses focus and gets stuck'        Mozilla Firefox
-    6 u"Newly installed plug-in doesn't seem to be used" Mozilla Firefox
-    9 u'mailto: problem in webpage'                mozilla-firefox in ubuntu
-    13 u'Problemas de Impress\xe3o no Firefox'     Mozilla Firefox
+    14 AINKAFSEEN ALEFLAMTEHGHAINYEHYEHREHALEFTEH ...   Ubuntu
+    1 Firefox cannot render Bank Site                   Mozilla Firefox
+    2 Problem showing the SVG demo on W3C site          Mozilla Firefox
+    4 Firefox loses focus and gets stuck                Mozilla Firefox
+    6 Newly installed plug-in doesn't seem to be used   Mozilla Firefox
+    9 mailto: problem in webpage                    mozilla-firefox in ubuntu
+    13 Problemas de Impressao no Firefox                Mozilla Firefox
 
-When no text search is done, the default sort order is
-QuestionSort.NEWEST_FIRST.
+When no text search is done, the default sort order is by newest first.
 
     >>> for question in question_set.searchQuestions(
-    ...     status=QuestionStatus.OPEN)[:5]:
-    ...     print question.id, repr(question.title), (
+    ...         status=QuestionStatus.OPEN)[:5]:
+    ...     print question.id, ascii_smash(question.title), (
     ...         question.target.displayname)
-    13 u'Problemas de Impress\xe3o no Firefox'   Mozilla Firefox
-    12 u'Problema al recompilar kernel con soporte smp (doble-n\xfacleo)' Ubuntu
-    11 u'Continue playing after shutdown'          Ubuntu
-     5 u'Installation failed'                      Ubuntu
-     4 u'Firefox loses focus and gets stuck'       Mozilla Firefox
-
-
-== getQuestionLanguages() ==
+    13 Problemas de Impressao no Firefox                Mozilla Firefox
+    12 Problema al recompilar kernel con soporte smp (doble-nucleo) Ubuntu
+    11 Continue playing after shutdown                  Ubuntu
+    5 Installation failed                               Ubuntu
+    4 Firefox loses focus and gets stuck Mozilla        Firefox
+
+
+Question languages
+==================
 
 The getQuestionLanguages() method returns the set of languages in which
-questions are written in Launchpad.
-
-    >>> sorted([language.code
-    ...         for language in question_set.getQuestionLanguages()])
-    [u'ar', u'en', u'es', u'pt_BR']
-
-
-== getActiveProjects() ==
-
-This method can be used to retrieve the projects that are the most
-actively using the Answer Tracker in the last 60 days. By active, we
-mean that the project is registered as officially using Answers and
-had some questions asked in the period. The projects are ordered
-by the number of questions asked during the period.
-
-Sample data should not contain any questions more recent than
-two months, so no projects are initially returned:
-
-    >>> for project in question_set.getMostActiveProjects():
-    ...     print project.displayname
-
-Create recent questions on a number of projects.
-
-    >>> from lp.answers.testing import (
-    ...     QuestionFactory)
-    >>> from canonical.launchpad.interfaces import (
-    ...     IDistributionSet, ILaunchBag, IProductSet)
-    >>> ubuntu = getUtility(IDistributionSet).getByName('ubuntu')
+questions are written in launchpad.
+
+    >>> print ', '.join(
+    ...     sorted(language.code
+    ...            for language in question_set.getQuestionLanguages()))
+    ar, en, es, pt_BR
+
+
+Active projects
+===============
+
+This method can be used to retrieve the projects that are the most actively
+using the Answer Tracker in the last 60 days.  By active, we mean that the
+project is registered as officially using Answers and had some questions asked
+in the period.  The projects are ordered by the number of questions asked
+during the period.
+
+Initially, no projects are returned.
+
+    >>> list(question_set.getMostActiveProjects())
+    []
+
+Then some recent questions are created on a number of projects.
+
+    >>> from lp.answers.testing import QuestionFactory
+    >>> from lp.registry.interfaces.distribution import IDistributionSet
+    >>> from lp.registry.interfaces.person import IPersonSet
+    >>> from lp.registry.interfaces.product import IProductSet
+
     >>> firefox = getUtility(IProductSet).getByName('firefox')
     >>> landscape = getUtility(IProductSet).getByName('landscape')
     >>> launchpad = getUtility(IProductSet).getByName('launchpad')
+    >>> no_priv = getUtility(IPersonSet).getByName('no-priv')
+    >>> ubuntu = getUtility(IDistributionSet).getByName('ubuntu')
 
     >>> login('[e-mail]')
-    >>> no_priv = getUtility(ILaunchBag).user
-    >>> QuestionFactory.createManyByProject([
+    >>> QuestionFactory.createManyByProject((
     ...     ('ubuntu', 3),
     ...     ('firefox', 2),
-    ...     ('landscape', 1)])
+    ...     ('landscape', 1),
+    ...     ))
 
-Create a question just before the time limit on Launchpad.
+A question is created just before the time limit on Launchpad.
 
     >>> from datetime import datetime, timedelta
     >>> from pytz import UTC
@@ -191,9 +204,9 @@
     ...     datecreated=datetime.now(UTC) - timedelta(days=61))
     >>> login(ANONYMOUS)
 
-The method returns only projects which officially use the Answer
-Tracker. The order of the returned projects is based on the number of
-questions asked during the period.
+The method returns only projects which officially use the Answer Tracker.  The
+order of the returned projects is based on the number of questions asked
+during the period.
 
     >>> ubuntu.official_answers
     True
@@ -204,14 +217,13 @@
     >>> launchpad.official_answers
     True
 
+    # Launchpad is not returned because the question was not asked in
+    # the last 60 days.
     >>> for project in question_set.getMostActiveProjects():
     ...     print project.displayname
     Ubuntu
     Mozilla Firefox
 
-(Launchpad is not returned because the question was not asked in
-the last 60 days.)
-
 The method accepts an optional limit parameter limiting the number of
 project returned:
 
@@ -220,10 +232,11 @@
     Ubuntu
 
 
-== getOpenQuestionCountByPackages() ==
+Counting the open questions
+===========================
 
-getOpenQuestionCountByPackages() allow you to get the count of open
-questions on a set of IDistributionSourcePackage packages.
+getOpenQuestionCountByPackages() allow you to get the count of open questions
+on a set of IDistributionSourcePackage packages.
 
     >>> question_set.getOpenQuestionCountByPackages([])
     {}
@@ -246,12 +259,10 @@
     >>> closed_question.setStatus(
     ...     closed_question.owner, QuestionStatus.SOLVED, 'no comment')
     <QuestionMessage at ...>
-    >>> from canonical.launchpad.ftests import syncUpdate
-    >>> syncUpdate(closed_question)
 
     >>> from operator import itemgetter
-    >>> packages = [
-    ...     ubuntu_evolution, ubuntu_pmount, debian_evolution, debian_pmount]
+    >>> packages = (
+    ...     ubuntu_evolution, ubuntu_pmount, debian_evolution, debian_pmount)
     >>> package_counts = question_set.getOpenQuestionCountByPackages(packages)
     >>> len(packages)
     4
@@ -263,5 +274,3 @@
     pmount (Ubuntu): 4
     evolution (Debian): 3
     pmount (Debian): 0
-
-

=== modified file 'lib/lp/answers/doc/questiontarget.txt'
--- lib/lp/answers/doc/questiontarget.txt	2009-03-24 12:43:49 +0000
+++ lib/lp/answers/doc/questiontarget.txt	2010-02-10 15:24:19 +0000
@@ -1,38 +1,43 @@
-= IQuestionTarget Interface =
-
-Launchpad includes an answer tracker. Questions are associated to
-objects implementing IQuestionTarget. This file documents that interface
-and can be used to validate implementation of this interface on a
-particular object. (This object is made available through the 'target'
-variable which is defined outside of this file, usually by a
-LaunchpadFunctionalTestCase. This instance shouldn't have any questions
-associated with it at the start of the test.)
-
+=========================
+IQuestionTarget interface
+=========================
+
+Launchpad includes an answer tracker.  Questions are associated to objects
+implementing IQuestionTarget.
+
+    # An IQuestionTarget object is made available to this test via the
+    # 'target' variable by the test framework.  It won't have any questions
+    # associated with it at the start of the test.  This is done because the
+    # exact same test applies to all types of question targets: products,
+    # distributions, and distribution source packages.
+    #
     # Some parts of the IQuestionTarget interface are only accessible
     # to a registered user.
     >>> login('[e-mail]')
 
     >>> from zope.component import getUtility
     >>> from zope.interface.verify import verifyObject
-    >>> from canonical.launchpad.interfaces import IQuestionTarget
+    >>> from lp.answers.interfaces.questiontarget import IQuestionTarget
 
     >>> verifyObject(IQuestionTarget, target)
     True
 
-== newQuestion() ==
+
+New questions
+=============
 
 Questions are always owned by a registered user.
 
-    >>> from canonical.launchpad.interfaces import IPersonSet
+    >>> from lp.registry.interfaces.person import IPersonSet
     >>> sample_person = getUtility(IPersonSet).getByEmail(
     ...     '[e-mail]')
 
-The newQuestion() method is used to create question that will be associated
-with the target. It takes as parameters the question's owner, title and
-description. It also takes an optional parameter 'datecreated' parameter
-which defaults to UTC_NOW.
+The newQuestion() method is used to create a question that will be associated
+with the target.  It takes as parameters the question's owner, title and
+description.  It also takes an optional parameter 'datecreated' which defaults
+to UTC_NOW.
 
-    # Let's define now to a know value.
+    # Initialize 'now' to a known value.
     >>> from datetime import datetime, timedelta
     >>> from pytz import UTC
     >>> now = datetime.now(UTC)
@@ -43,8 +48,8 @@
     New question
     >>> print question.description
     Question description
-    >>> question.owner == sample_person
-    True
+    >>> print question.owner.displayname
+    Sample Person
     >>> question.datecreated == now
     True
     >>> question.datelastquery == now
@@ -53,41 +58,44 @@
 The created question starts in the 'Open' status and should have the owner
 subscribed to the question.
 
-    >>> question.status.title
-    'Open'
-
-    >>> sample_person in [s.person for s in question.subscriptions]
-    True
-
-Question can be written in any languages supported in Launchpad. The
-language of the request is available in the 'language' attribute. By
-default, requests are assumed to be written in English:
+    >>> print question.status.title
+    Open
+
+    >>> for subscription in question.subscriptions:
+    ...     print subscription.person.displayname
+    Sample Person
+
+Questions can be written in any languages supported in Launchpad.  The
+language of the request is available in the 'language' attribute.  By default,
+requests are assumed to be written in English.
 
     >>> print question.language.code
     en
 
-It is possible to create question in another language than English. One
-just need to pass the language in which the question is written in the
-language parameter.
+It is possible to create questions in another language than English, by
+passing in the language that the question is written in.
 
-    >>> from canonical.launchpad.interfaces import ILanguageSet
+    >>> from lp.services.worlddata.interfaces.language import ILanguageSet
     >>> french = getUtility(ILanguageSet)['fr']
-    >>> question = target.newQuestion(sample_person, "De l'aide S.V.P.",
+    >>> question = target.newQuestion(
+    ...     sample_person, "De l'aide S.V.P.",
     ...     "Pouvez-vous m'aider?", language=french,
     ...     datecreated=now + timedelta(seconds=30))
     >>> print question.language.code
     fr
 
-Anonymous users cannot use newQuestion():
+Anonymous users cannot use newQuestion().
 
     >>> login(ANONYMOUS)
-    >>> question = target.newQuestion(sample_person, 'This will fail',
-    ...     'Failed?')
+    >>> question = target.newQuestion(
+    ...     sample_person, 'This will fail', 'Failed?')
     Traceback (most recent call last):
       ...
     Unauthorized...
 
-== getQuestion() ==
+
+Retrieving questions
+====================
 
 The getQuestion() method is used to retrieve a question by id for a
 particular target.
@@ -96,19 +104,19 @@
     True
 
 If you pass in a non-existent id or a question for a different target, the
-method must return None.
-
-    >>> target.getQuestion(2) is None
-    True
-    >>> target.getQuestion(12345) is None
-    True
-
-== Creating some additional questions ==
-
-For the following methods, we will require some more questions. Create five
-new questions. Odd questions will be owned by foo_bar and even questions will be
-owned by sample_person.
-
+method returns None.
+
+    >>> print target.getQuestion(2)
+    None
+    >>> print target.getQuestion(12345)
+    None
+
+
+Searching for questions
+=======================
+
+    # Create new questions for the following tests.  Odd questions will be
+    # owned by Foo Bar and even questions will be owned by Sample Person.
     >>> login('[e-mail]')
     >>> foo_bar = getUtility(IPersonSet).getByEmail('[e-mail]')
     >>> questions = []
@@ -123,9 +131,8 @@
     ...         owner, 'Question title%d' % num, description,
     ...         datecreated=now+timedelta(minutes=num+1)))
 
-For more variety, we will set the status of the last to INVALID and the
-fourth one to ANSWERED.
-
+    # For more variety, we will set the status of the last to INVALID and the
+    # fourth one to ANSWERED.
     >>> login('[e-mail]')
     >>> foo_bar = getUtility(IPersonSet).getByEmail('[e-mail]')
     >>> message = questions[-1].reject(
@@ -134,48 +141,44 @@
     ...     sample_person, 'This is your answer.',
     ...     datecreated=now+timedelta(hours=1))
 
-Also add a reply from the owner on the first of these.
-
+    # Also add a reply from the owner on the first of these.
     >>> login('[e-mail]')
     >>> message = questions[0].giveInfo(
     ...     'I think I forgot something.', datecreated=now+timedelta(hours=4))
 
-And create another one that will also have the word 'new' in its
-description.
-
+    # Create another one that will also have the word 'new' in its
+    # description.
     >>> question = target.newQuestion(sample_person, 'Another question',
     ...     'Another new question that is actually very new.',
     ...     datecreated=now+timedelta(hours=1))
     >>> login(ANONYMOUS)
 
-    # Flush those changes to the database.
-    >>> from canonical.database.sqlbase import flush_database_updates
-    >>> flush_database_updates()
-
-== searchQuestions() ==
-
 The searchQuestions() method is used to search for questions.
 
-=== search_text ===
+
+Search text
+-----------
 
 The search_text parameter will select the questions that contain the
-passed in text. (The standard text searching algorithm is used, see
-textsearching.txt.)
+passed in text.  The standard text searching algorithm is used; see
+../../../canonical/launchpad/doct/textsearching.txt.
 
     >>> for t in target.searchQuestions(search_text='new'):
     ...     print t.title
     New question
     Another question
 
-The results here are sorted by relevancy. (In the last questions, 'New'
-appeared in the description which makes it less relevant than when the
-word appears in the title.)
-
-=== status ===
-
-The searchQuestions() method can also filter questions by status:
-
-    >>> from canonical.launchpad.interfaces import QuestionStatus
+The results are sorted by relevancy.  In the last questions, 'New' appeared in
+the description which makes it less relevant than when the word appears in the
+title.
+
+
+Status
+------
+
+The searchQuestions() method can also filter questions by status.
+
+    >>> from lp.answers.interfaces.questionenums import QuestionStatus
     >>> for t in target.searchQuestions(status=QuestionStatus.OPEN):
     ...     print t.title
     Another question
@@ -192,9 +195,9 @@
     ...     print t.title
     Question title4
 
-You can also pass in a list of status, and you can also use the
-search_text and status parameters at the same time. This will search
-OPEN and INVALID questions with the word 'index'
+You can pass in a list of statuses, and you can also use the search_text and
+status parameters at the same time.  This will search OPEN and INVALID
+questions with the word 'index'.
 
     >>> for t in target.searchQuestions(search_text='request index',
     ...         status=(QuestionStatus.OPEN, QuestionStatus.INVALID)):
@@ -204,29 +207,30 @@
     Question title1
     Question title0
 
-=== sort ===
-
-You can control the sort order by passing one of the constants defined
-in QuestionSort. (We already saw the NEWEST_FIRST and RELEVANCY sort
-order).
-
-You can sort also from oldest to newest using the OLDEST_FIRST constant:
-
-    >>> from canonical.launchpad.interfaces import QuestionSort
-
+
+Sorting
+-------
+
+You can control the sort order by passing one of the constants defined in
+QuestionSort.  Previously, we saw the NEWEST_FIRST and RELEVANCY sort order.
+
+You can sort also from oldest to newest using the OLDEST_FIRST constant.
+
+    >>> from lp.answers.interfaces.questionenums import QuestionSort
     >>> for t in target.searchQuestions(search_text='new',
-    ...                               sort=QuestionSort.OLDEST_FIRST):
+    ...                                 sort=QuestionSort.OLDEST_FIRST):
     ...     print t.title
     New question
     Another question
 
-You can sort by status, (the status order is OPEN, NEEDSINFO, ANSWERED,
-SOLVED, EXPIRED, INVALID), this also sorts from newest to oldest as a
-secondary key.
+You can sort by status (the status order is OPEN, NEEDSINFO, ANSWERED, SOLVED,
+EXPIRED, INVALID).  This also sorts from newest to oldest as a secondary key.
+Here we use status=None to search for all statuses; by default INVALID and
+EXPIRED questions are excluded.
 
     >>> for t in target.searchQuestions(search_text='request index',
-    ...                               status=None,
-    ...                               sort=QuestionSort.STATUS):
+    ...                                 status=None,
+    ...                                 sort=QuestionSort.STATUS):
     ...     print t.status.title, t.title
     Open Question title2
     Open Question title1
@@ -234,12 +238,11 @@
     Answered Question title3
     Invalid Question title4
 
-(In the previous example, we used status=None to search for all
-statuses, by default INVALID and EXPIRED questions are excluded.)
-
 If there is no search_text and the requested sort order is RELEVANCY,
 the questions will be sorted NEWEST_FIRST.
 
+    # 'Question title4' is not shown in this case because it has INVALID as
+    # its status.
     >>> for t in target.searchQuestions(sort=QuestionSort.RELEVANCY):
     ...     print t.title
     Another question
@@ -250,14 +253,14 @@
     De l'aide S.V.P.
     New question
 
-('Question title4' is not shown in this case because it has INVALID as
-its status.)
-
 The RECENT_OWNER_ACTIVITY sort order sorts first questions which recently
-received a new message by their owner. (It effectively sorts
-descending on the datelastquery attribute.)
+received a new message by their owner.  It effectively sorts descending on the
+datelastquery attribute.
 
-    >>> for t in target.searchQuestions(sort=QuestionSort.RECENT_OWNER_ACTIVITY):
+    # Question title0 sorts first because it has a message from its owner
+    # after the others were created.
+    >>> for t in target.searchQuestions(
+    ...                             sort=QuestionSort.RECENT_OWNER_ACTIVITY):
     ...     print t.title
     Question title0
     Another question
@@ -267,20 +270,20 @@
     De l'aide S.V.P.
     New question
 
-(Question title0 sorts first because it had a message from its owner
-after the others were created.)
-
-=== owner ===
-
-You can also find question owner by a particular user by using the owner
-parameter.
+
+Owner
+-----
+
+You can find question owned by a particular user by using the owner parameter.
 
     >>> for t in target.searchQuestions(owner=foo_bar):
     ...     print t.title
     Question title3
     Question title1
 
-=== language ===
+
+Language
+---------
 
 The language criteria can be used to select only questions written in a
 particular language.
@@ -290,7 +293,7 @@
     ...     print t.title
     De l'aide S.V.P.
 
-    >>> for t in target.searchQuestions(language=[english, french]):
+    >>> for t in target.searchQuestions(language=(english, french)):
     ...     print t.title
     Another question
     Question title3
@@ -300,39 +303,40 @@
     De l'aide S.V.P.
     New question
 
-=== needs_attention_from ===
-
-You can also search among the questions that needs the attention of
-somebody. A question needs the attention of a user if he owns it and that
-it is in the NEEDSINFO or ANSWERED state. Questions on which the user gave
-an answer or requested for more information and that are back in the
-OPEN state are also included.
+
+Questions needing attention
+---------------------------
+
+You can search among the questions that need attention.  A question needs the
+attention of a user if he owns it and if it is in the NEEDSINFO or ANSWERED
+state.  Questions on which the user gave an answer or requested for more
+information, and that are back in the OPEN state, are also included.
 
     # One of Sample Person's question gets to need attention from Foo Bar.
     >>> login('[e-mail]')
     >>> message = questions[0].requestInfo(
     ...     foo_bar, 'Do you have a clue?',
     ...     datecreated=now+timedelta(hours=1))
+
     >>> login('[e-mail]')
     >>> message = questions[0].giveInfo(
-    ... 'I do, now please help me.', datecreated=now+timedelta(hours=2))
+    ...     'I do, now please help me.', datecreated=now+timedelta(hours=2))
 
-    # Another one of Foo Bar's question needs attention.
+    # Another one of Foo Bar's questions needs attention.
     >>> message = questions[1].requestInfo(
     ...     sample_person, 'And you, do you have a clue?',
     ...     datecreated=now+timedelta(hours=1))
 
-    # Flush those changes to the database.
-    >>> flush_database_updates()
     >>> login(ANONYMOUS)
-
     >>> for t in target.searchQuestions(needs_attention_from=foo_bar):
     ...     print t.status.title, t.title, t.owner.displayname
     Answered Question title3 Foo Bar
     Needs information Question title1 Foo Bar
     Open Question title0 Sample Person
 
-=== unsupported ===
+
+Unsupported language
+--------------------
 
 The 'unsupported' criteria is used to select questions that are in a
 language that is not spoken by any of the Support Contacts.
@@ -341,40 +345,42 @@
     ...     print t.title
     De l'aide S.V.P.
 
-== findSimilarQuestions() ==
-
-The method findSimilarQuestions() can be use to find questions similar to a
-sentence. The questions don't have to contain all the words of the sentence,
-just some.
-
+
+Finding similar questions
+=========================
+
+The method findSimilarQuestions() can be use to find questions similar to some
+target text.  The questions don't have to contain all the words of the text.
+
+    # This returns the same results as with the search 'new' because
+    # all other words in the text are either common ('question', 'title') or
+    # stop words ('with', 'a').
     >>> for t in target.findSimilarQuestions('new questions with a title'):
     ...     print t.title
     New question
     Another question
 
-In this case, it returned the same results than with the search 'new' because
-all other words in the sentence are either common ('question', 'title') or stop
-words ('with', 'a').
-
-== Answer contacts ==
-
-Target can have answer contacts. The list of answer contacts for a
+
+Answer contacts
+===============
+
+Targets can have answer contacts.  The list of answer contacts for a
 target is available through the answer_contacts attribute.
 
     >>> list(target.answer_contacts)
     []
 
-There is also a direct_answer_contacts which includes only the
-answer contacts registered explicitly on the question target. (In
-general, it will be equal to answer_contacts attribute, but some
-IQuestionTarget implementations may inherit answer contacts
-from other context. In these cases, that attribute would only contain
-the answer contacts defined in the current IQuestionTarget context.)
+There is also a direct_answer_contacts which includes only the answer contacts
+registered explicitly on the question target.  In general, this will be the
+same as the answer_contacts attribute, but some IQuestionTarget
+implementations may inherit answer contacts from other contexts.  In these
+cases, the direct_answer_contacts attribute would only contain the answer
+contacts defined in the current IQuestionTarget context.
 
     >>> list(target.direct_answer_contacts)
     []
 
-You add an answer contact by using the addAnswerContact method. This
+You add an answer contact by using the addAnswerContact() method.  This
 is only available to registered users.
 
     >>> name18 = getUtility(IPersonSet).getByName('name18')
@@ -382,22 +388,28 @@
     Traceback (most recent call last):
       ...
     Unauthorized...
+
+This method returns True when the contact was added the list and False when it
+was already on the list.
+
     >>> login('[e-mail]')
-
-This method will return True when the contact was added the list and
-False when it was already on the list:
-
     >>> target.addAnswerContact(name18)
     True
-    >>> [p.name for p in target.answer_contacts]
-    [u'name18']
-    >>> [p.name for p in target.direct_answer_contacts]
-    [u'name18']
+    >>> people = [p.name for p in target.answer_contacts]
+    >>> len(people)
+    1
+    >>> print people[0]
+    name18
+    >>> people = [p.name for p in target.direct_answer_contacts]
+    >>> len(people)
+    1
+    >>> print people[0]
+    name18
     >>> target.addAnswerContact(name18)
     False
 
-An answer contact must have at least one language among his
-preferred languages.
+An answer contact must have at least one language among his preferred
+languages.
 
     >>> sample_person = getUtility(IPersonSet).getByName('name12')
     >>> len(sample_person.languages)
@@ -407,10 +419,9 @@
       ...
     AssertionError: An Answer Contact must speak a language...
 
-Answer contacts can be removed by using the removeAnswerContact()
-method. Like its counterpart, it returns True when the answer contact
-was removed and False when the person wasn't on the answer contact
-list.
+Answer contacts can be removed by using the removeAnswerContact() method.
+Like its counterpart, it returns True when the answer contact was removed and
+False when the person wasn't on the answer contact list.
 
     >>> target.removeAnswerContact(name18)
     True
@@ -421,7 +432,7 @@
     >>> target.removeAnswerContact(name18)
     False
 
-Only registered users can remove an answer contact:
+Only registered users can remove an answer contact.
 
     >>> login(ANONYMOUS)
     >>> target.removeAnswerContact(name18)
@@ -429,85 +440,102 @@
       ...
     Unauthorized...
 
-== Supported Languages ==
+
+Supported languages
+===================
 
 The supported languages for a given IQuestionTarget are given by
-getSupportedLanguages(). The supported languages of a question target
-include all languages spoken by at least one of its answer contacts,
-with the exception of all English variations. English is the assumed
-language for support when there are no answer contacts.
-
-    >>> [lang.code for lang in target.getSupportedLanguages()]
-    [u'en']
-
-Let's add some answer contacts which speak different languages.
-
+getSupportedLanguages().  The supported languages of a question target include
+all languages spoken by at least one of its answer contacts, with the
+exception of all English variations since English is the assumed language for
+support when there are no answer contacts.
+
+    >>> codes = [lang.code for lang in target.getSupportedLanguages()]
+    >>> len(codes)
+    1
+    >>> print codes[0]
+    en
+
+    # Let's add some answer contacts which speak different languages.
     >>> login('[e-mail]')
     >>> carlos = getUtility(IPersonSet).getByName('carlos')
-    >>> [lang.code for lang in carlos.languages]
-    [u'ca', u'en', u'es']
+    >>> for language in carlos.languages:
+    ...     print language.code
+    ca
+    en
+    es
     >>> target.addAnswerContact(carlos)
     True
 
-Note that daf has en_GB as one of his preferred languages...
+While daf has en_GB as one of his preferred languages...
 
     >>> login('[e-mail]')
     >>> daf = getUtility(IPersonSet).getByName('daf')
-    >>> [lang.code for lang in daf.languages]
-    [u'en_GB', u'ja', u'cy']
+    >>> for language in daf.languages:
+    ...     print language.code
+    en_GB
+    ja
+    cy
     >>> target.addAnswerContact(daf)
     True
 
-... but en_GB is not included in the target's supported languages,
-because we convert all English variants to English.
-
-    >>> import operator
-    >>> [lang.code for lang in sorted(target.getSupportedLanguages(),
-    ...                               key=operator.attrgetter('code'))]
-    [u'ca', u'cy', u'en', u'es', u'ja']
-
-
-== getAnswerContactsForLanguage() ==
-
-Continuing from the previous section with Carlos and Daf, the
-getAnswerContactsForLanguage() method returns a list of answer contacts
-who support the specified language in their preferred languages. Daf
-is in the list because he speaks an English variant, which is treated
-as English.
+...en_GB is not included in the target's supported languages, because all
+English variants are converted to English.
+
+    >>> from operator import attrgetter
+    >>> print ', '.join(
+    ...     language.code
+    ...     for language in sorted(target.getSupportedLanguages(),
+    ...                            key=attrgetter('code')))
+    ca, cy, en, es, ja
+
+
+Answer contacts for languages
+=============================
+
+getAnswerContactsForLanguage() method returns a list of answer contacts who
+support the specified language in their preferred languages.  Daf is in the
+list because he speaks an English variant, which is treated as English.
 
     >>> spanish = getUtility(ILanguageSet)['es']
     >>> answer_contacts = target.getAnswerContactsForLanguage(spanish)
-    >>> sorted([person.name for person in answer_contacts])
-    [u'carlos']
+    >>> for person in answer_contacts:
+    ...     print person.name
+    carlos
 
     >>> answer_contacts = target.getAnswerContactsForLanguage(english)
-    >>> sorted([person.name for person in answer_contacts])
-    [u'carlos', u'daf']
-
-
-== getQuestionLanguages() ==
+    >>> for person in answer_contacts:
+    ...     print person.name
+    carlos
+    daf
+
+
+A question's languages
+======================
 
 The getQuestionLanguages() method returns the set of languages used by all
 of the target's questions.
 
-    >>> sorted([language.code for language in target.getQuestionLanguages()])
-    [u'en', u'fr']
-
-
-== createQuestionFromBug() ==
-
-The target can create a question from a bug, and link that bug to the
-new question. The question owner is the same as the bug owner. The
-question title and description are taken from the bug. The messages on
-the bug are copied to the question.
+    >>> print ', '.join(
+    ...     sorted(language.code
+    ...            for language in target.getQuestionLanguages()))
+    en, fr
+
+
+Creating questions from bugs
+============================
+
+The target can create a question from a bug, and link that bug to the new
+question.  The question's owner is the same as the bug's owner.  The question
+title and description are taken from the bug.  The comments on the bug are
+copied to the question.
 
     >>> from datetime import datetime
     >>> from pytz import UTC
-    >>> from canonical.launchpad.interfaces import (
-    ...     CreateBugParams, IBugSet, IProductSet)
+    >>> from lp.bugs.interfaces.bug import CreateBugParams, IBugSet
+    >>> from lp.registry.interfaces.product import IProductSet
 
     >>> now = datetime.now(UTC)
-
     >>> target = getUtility(IProductSet)['jokosher']
     >>> bug_params = CreateBugParams(
     ...     title="Print is broken", comment="blah blah blah",
@@ -519,41 +547,34 @@
 
     >>> target_question = target.createQuestionFromBug(target_bug)
 
-    >>> target_question.owner == target_bug.owner
-    True
-    >>> target_question.title == target_bug.title
-    True
-    >>> target_question.description == target_bug.description
-    True
+    >>> print target_question.owner.displayname
+    Sample Person
+    >>> print target_question.title
+    Print is broken
+    >>> print target_question.description
+    blah blah blah
     >>> question_message = target_question.messages[-1]
-    >>> question_message.text_contents == bug_message.text_contents
-    True
-
-    >>> target_question.owner.displayname
-    u'Sample Person'
-    >>> target_question.title
-    u'Print is broken'
-    >>> target_question.description
-    u'blah blah blah'
-    >>> [bug_link.bug.title for bug_link in target_question.bug_links]
-    [u'Print is broken']
-    >>> target_question.messages[-1].text_contents
-    u'This is really a question.'
-
-The question's datecreated attribute is the same as the bug's
-datecreated. The question's datelastresponse attribute has a current
-datetime stamp to indicate the question is active. The question janitor
-would otherwise mistake the questions made from old bugs as old
-questions and would expire them.
+    >>> print question_message.text_contents
+    This is really a question.
+
+    >>> for bug_link in target_question.bug_links:
+    ...     print bug_link.bug.title
+    Print is broken
+    >>> print target_question.messages[-1].text_contents
+    This is really a question.
+
+The question's creation date is the same as the bug's creation date.  The
+question's last response date has a current datetime stamp to indicate the
+question is active.  The question janitor would otherwise mistake the
+questions made from old bugs as old questions and would expire them.
 
     >>> target_question.datecreated == target_bug.datecreated
     True
     >>> target_question.datelastresponse > now
     True
 
-The question language is always English because all bugs in Launchpad
-are written in English.
-
-    >>> target_question.language.code
-    u'en'
-
+The question language is always English because all bugs in Launchpad are
+written in English.
+
+    >>> print target_question.language.code
+    en

=== modified file 'lib/lp/answers/doc/workflow.txt'
--- lib/lp/answers/doc/workflow.txt	2009-07-13 05:48:57 +0000
+++ lib/lp/answers/doc/workflow.txt	2010-02-10 15:24:19 +0000
@@ -1,11 +1,13 @@
-= Answer Tracker Workflow =
-
-The state of a question is tracked through its status attribute.
-Six statuses are used to model a question lifecycle. These are defined
-in the QuestionStatus enumeration.
-
-    >>> from canonical.launchpad.interfaces import QuestionStatus
-    >>> print "\n".join([status.name for status in QuestionStatus.items])
+=======================
+Answer tracker workflow
+=======================
+
+The state of a question is tracked through its status, which model a
+question's lifecycle.  These are defined in the QuestionStatus enumeration.
+
+    >>> from lp.answers.interfaces.questionenums import QuestionStatus
+    >>> for status in QuestionStatus.items:
+    ...     print status.name
     OPEN
     NEEDSINFO
     ANSWERED
@@ -13,11 +15,12 @@
     EXPIRED
     INVALID
 
-Status change occurs in consequence of a user action. The possible
+Status change occurs as a consequence of a user's action.  The possible
 actions are defined in the QuestionAction enumeration.
 
-    >>> from canonical.launchpad.interfaces import QuestionAction
-    >>> print "\n".join([status.name for status in QuestionAction.items])
+    >>> from lp.answers.interfaces.questionenums import QuestionAction
+    >>> for status in QuestionAction.items:
+    ...     print status.name
     REQUESTINFO
     GIVEINFO
     COMMENT
@@ -28,19 +31,18 @@
     REOPEN
     SETSTATUS
 
-There is a method available to execute each of these defined actions.
+Each defined action can be executed.
 
-Let's define the actors that we are going to use to demonstrate the
-Answer Tracker workflow. The 'No Privileges Person' will be the
-submitter of questions, 'Sample Person' will be an answer contact for
-the Ubuntu distribution, and 'Marilize Coetze' will be another user
-providing support. Stub is a launchpad administrator that isn't also in
-the Ubuntu Team that owns the distribution.
+No Privileges Person is the submitter of questions.  Sample Person is an
+answer contact for the Ubuntu distribution.  Marilize Coetze is another user
+providing support.  Stub is a Launchpad administrator that isn't also in the
+Ubuntu Team owning the distribution.
 
     >>> login('[e-mail]')
 
-    >>> from canonical.launchpad.interfaces import (
-    ...     IDistributionSet, ILanguageSet, IPersonSet)
+    >>> from lp.registry.interfaces.distribution import IDistributionSet
+    >>> from lp.registry.interfaces.person import IPersonSet
+    >>> from lp.services.worlddata.interfaces.language import ILanguageSet
 
     >>> personset = getUtility(IPersonSet)
     >>> sample_person = personset.getByEmail('[e-mail]')
@@ -63,28 +65,31 @@
     >>> from datetime import datetime, timedelta
     >>> from pytz import UTC
     >>> now = datetime.now(UTC)
-    >>> new_question_args = {
-    ...     'owner': no_priv,
-    ...     'title': 'Unable to boot installer',
-    ...     'description': "I've tried installing Ubuntu on a Mac. "
-    ...     "But the installer never boots.",
-    ...     'datecreated': now}
+    >>> new_question_args = dict(
+    ...     owner=no_priv,
+    ...     title='Unable to boot installer',
+    ...     description="I've tried installing Ubuntu on a Mac. "
+    ...                 "But the installer never boots.",
+    ...     datecreated=now,
+    ...     )
     >>> question = ubuntu.newQuestion(**new_question_args)
     >>> print question.status.title
     Open
 
-From there, we have four representative scenarios.
-
-== 1) Another user helps the submitter with his question ==
-
-The most common scenario is where another user comes to help the
-submitter and answers his question. This may involve exchanging
-information with the submitter to clarify the question.
-
-The requestInfo() method is used to ask the user for more information.
-This method takes two mandatory parameters: the user making the question
-and his question. It can also takes a 'datecreated' parameter specifying
-the creation date of the question (which defaults to now).
+The following scenarios are now possible.
+
+
+1) Another user helps the submitter with his question
+=====================================================
+
+The most common scenario is where another user comes to help the submitter and
+answers his question.  This may involve exchanging information with the
+submitter to clarify the question.
+
+The requestInfo() method is used to ask the user for more information.  This
+method takes two mandatory parameters: the user asking the question and his
+question.  It can also takes a 'datecreated' parameter specifying the creation
+date of the question (which defaults to 'now').
 
     >>> question = ubuntu.newQuestion(**new_question_args)
     >>> now_plus_one_hour = now + timedelta(hours=1)
@@ -92,11 +97,11 @@
     ...     sample_person, 'What is your Mac model?',
     ...     datecreated=now_plus_one_hour)
 
-It returns the IQuestionMessage that was added to the question messages
-history:
+We now have the IQuestionMessage that was added to the question messages
+history.
 
     >>> from canonical.launchpad.webapp.testing import verifyObject
-    >>> from canonical.launchpad.interfaces import IQuestionMessage
+    >>> from lp.answers.interfaces.questionmessage import IQuestionMessage
     >>> verifyObject(IQuestionMessage, request_message)
     True
     >>> request_message == question.messages[-1]
@@ -106,9 +111,8 @@
     >>> print request_message.owner.displayname
     Sample Person
 
-The question message contains the action that was executed in the action
-attribute and the status of the question after the action was executed in
-the new_status attribute:
+The question message contains the action that was executed and the status of
+the question after the action was executed.
 
     >>> print request_message.action.name
     REQUESTINFO
@@ -118,13 +122,13 @@
     >>> print request_message.text_contents
     What is your Mac model?
 
-The subject of the message was generated automatically:
+The subject of the message was generated automatically.
 
     >>> print request_message.subject
     Re: Unable to boot installer
 
-The question is moved to the NEEDSINFO state and the datelastresponse
-attribute is updated to the message timestamp.
+The question is moved to the NEEDSINFO state and the last response date is
+updated to the message's timestamp.
 
     >>> print question.status.name
     NEEDSINFO
@@ -148,33 +152,35 @@
     >>> print reply_message.owner.displayname
     No Privileges Person
 
-The question is moved back to the OPEN state and the 'datelastquery'
-attribute is updated to the message's creation date:
+The question is moved back to the OPEN state and the last query date is
+updated to the message's creation date.
 
     >>> print question.status.name
     OPEN
     >>> question.datelastquery == now_plus_two_hours
     True
 
-The other user has now enough information to give an answer to the
-question. The giveAnswer() method is used for that purpose. Like the
-requestInfo() method, it takes two mandatory parameters: the user
-providing the answer and the answer itself.
+Now, the other user has enough information to give an answer to the question.
+The giveAnswer() method is used for that purpose.  Like the requestInfo()
+method, it takes two mandatory parameters: the user providing the answer and
+the answer itself.
 
     >>> login('[e-mail]')
     >>> now_plus_three_hours = now + timedelta(hours=3)
     >>> answer_message = question.giveAnswer(
-    ...     sample_person, "You need some configuration on the Mac side "
+    ...     sample_person,
+    ...     "You need some configuration on the Mac side "
     ...     "to boot the installer on that model. Consult "
     ...     "https://help.ubuntu.com/community/Installation/OldWorldMacs "
-    ...     "for all the details.", datecreated=now_plus_three_hours)
+    ...     "for all the details.",
+    ...     datecreated=now_plus_three_hours)
     >>> print answer_message.action.name
     ANSWER
     >>> print answer_message.new_status.name
     ANSWERED
 
-After that action, the question's status is changed to ANSWERED and the
-datelastresponse is updated to contain the date of the message.
+The question's status is changed to ANSWERED and the last response date is
+updated to contain the date of the message.
 
     >>> print question.status.name
     ANSWERED
@@ -182,9 +188,8 @@
     True
 
 At that point, the question is considered answered, but we don't have
-feedback from the user on whether it solved his problem or not. If it
-doesn't the user can reopen the question. The reopen() method is used
-for that purpose.
+feedback from the user on whether it solved his problem or not.  If it
+doesn't, the user can reopen the question.
 
     >>> login('[e-mail]')
     >>> tomorrow = now + timedelta(days=1)
@@ -200,38 +205,37 @@
     >>> print reopen_message.owner.displayname
     No Privileges Person
 
-This moves back the question to the OPEN state and the datelastquery
-attribute is updated to the message creation date.
+This moves back the question to the OPEN state and the last query date is
+updated to the message's creation date.
 
     >>> print question.status.name
     OPEN
     >>> question.datelastquery == tomorrow
     True
 
-The giveAnswer() will again be used to give an answer.
+Once again, an answer is given.
 
     >>> login('[e-mail]')
     >>> tomorrow_plus_one_hour = tomorrow + timedelta(hours=1)
     >>> answer2_message = question.giveAnswer(
-    ...     marilize, "You probably do not have enough RAM to use the "
+    ...     marilize,
+    ...     "You probably do not have enough RAM to use the "
     ...     "graphical installer. You can try the alternate CD with the "
     ...     "text installer.")
 
-This again moves the question to the ANSWERED state.
+The question is moved back to the ANSWERED state.
 
     >>> print question.status.name
     ANSWERED
 
-The question owner will hopefully come back to confirm that his
-problem is solved. He can specify which answer message helped him
-solved his problem. The confirmAnswer() method is used for that
-purpose.
+The question owner will hopefully come back to confirm that his problem is
+solved.  He can specify which answer message helped him solved his problem.
 
     >>> login('[e-mail]')
     >>> two_weeks_from_now = now + timedelta(days=14)
     >>> confirm_message = question.confirmAnswer(
     ...     "I upgraded to 512M of RAM (found on eBay) and I've "
-    ...     "succesfully managed to install Ubuntu. Thanks for all the help.",
+    ...     "successfully managed to install Ubuntu. Thanks for all the help.",
     ...     datecreated=two_weeks_from_now, answer=answer_message)
     >>> print confirm_message.action.name
     CONFIRM
@@ -240,9 +244,9 @@
     >>> print confirm_message.owner.displayname
     No Privileges Person
 
-The question is moved to the SOLVED state, the message that solved
-the question is saved in the answer attribute, the date_solved
-and answerer attributes are also updated.
+The question is moved to the SOLVED state, and the message that solved the
+question is saved.  The date the question was solved and answerer are also
+updated.
 
     >>> print question.status.name
     SOLVED
@@ -254,45 +258,43 @@
     True
 
 
-== 2) Self-answer ==
-
-Another scenario is for the case when the user comes back to give the
-solution to the question himself. The giveAnswer() method is also used
-for that case. The question owner can choose a best answer message
-later on. The workflow permits the question owner to choose an answer
-before or after the question status is set to SOLVED.
-
-The question owner creates a question.
+2) Self-answering
+=================
+
+In this scenario the user comes back to give the solution to the question
+himself.  The question owner can choose a best answer message later on.  The
+workflow permits the question owner to choose an answer before or after the
+question status is set to SOLVED.
+
+A new question is posed.
 
     >>> question = ubuntu.newQuestion(**new_question_args)
 
-The question answer provides an answer that eludes to a decision
-the question owner must make.
+The answer provides some useful information to the questioner.
 
     >>> login('[e-mail]')
     >>> tomorrow_plus_one_hour = tomorrow + timedelta(hours=1)
     >>> alt_answer_message = question.giveAnswer(
-    ...     marilize, "Are you using a pre-G3 Mac? They are very difficult "
+    ...     marilize,
+    ...     "Are you using a pre-G3 Mac? They are very difficult "
     ...     "to install to. You must mess with the hardware to trick "
     ...     "the core chips to let it install. You may not want to do this.")
 
-The question owner logs in, and explains that he has researched the
-problem, and come to a solution.
+The question has researched the problem, and has comes to a solution himself.
 
     >>> login('[e-mail]')
     >>> self_answer_message = question.giveAnswer(
-    ...     no_priv, "I found some instructions on the Wiki on how to "
+    ...     no_priv,
+    ...     "I found some instructions on the Wiki on how to "
     ...     "install BootX to boot the installation CD on OldWorld Mac: "
     ...     "https://help.ubuntu.com/community/Installation/OldWorldMacs "
     ...     "This is complicated and since it's a very old machine, not "
     ...     "worth the trouble.",
     ...     datecreated=now_plus_one_hour)
 
-In that case, the question owner is considered to have given
-information that the problem is solved and the question is moved to
-the SOLVED state. The 'answerer' attribute will be the question owner,
-the 'date_solved' date of the message, but the 'answer' attribute
-will None.
+The question owner is considered to have given information that the problem is
+solved and the question is moved to the SOLVED state.  The 'answerer'
+will be the question owner.
 
     >>> print self_answer_message.action.name
     CONFIRM
@@ -305,20 +307,20 @@
     No Privileges Person
     >>> question.date_solved == now_plus_one_hour
     True
-    >>> question.answer is None
-    True
+    >>> print question.answer
+    None
 
-The question owner can still specify which message helped him solved
-his problem. The confirmAnswer() method is used when the question
-owner chooses another user's answer as a best answer. The status
-will remain SOLVED. The 'answerer' attribute will be the message
-owner, and the 'answer' will be the message. The question's
-'date_solved' attribute will be the date of the answer message.
+The question owner can still specify which message helped him solved his
+problem.  The confirmAnswer() method is used when the question owner chooses
+another user's answer as a best answer.  The status will remain SOLVED.  The
+'answerer' will be the message owner, and the 'answer' will be the message.
+The question's solution date will be the date of the answer message.
 
     >>> confirm_message = question.confirmAnswer(
     ...     "Thanks Marilize for your help. I don't think I'll put Ubuntu "
     ...     "Ubuntu on my Mac.",
-    ...     datecreated=now_plus_one_hour, answer=alt_answer_message)
+    ...     datecreated=now_plus_one_hour,
+    ...     answer=alt_answer_message)
     >>> print confirm_message.action.name
     CONFIRM
     >>> print confirm_message.new_status.name
@@ -336,17 +338,18 @@
     True
 
 
-== 3) The question expires ==
+3) The question expires
+=======================
 
-Another case is when nobody comes to answer the message, either because
-the question is too complex or too vague. These questions can be expired
-by using the expireQuestion() method. (See answer-tracker-expiration.txt
-for the documentation of the cron script handling this task.)
+It is also possible that nobody will answer the question, either because the
+question is too complex or too vague.  These questions are expired by using
+the expireQuestion() method.
 
     >>> login('[e-mail]')
     >>> question = ubuntu.newQuestion(**new_question_args)
     >>> expire_message = question.expireQuestion(
-    ...     sample_person, "There was no activity on this question for two "
+    ...     sample_person,
+    ...     "There was no activity on this question for two "
     ...     "weeks and this question was expired. If you are still having "
     ...     "this problem you should reopen the question and provide more "
     ...     "information about your problem.",
@@ -356,8 +359,8 @@
     >>> print expire_message.new_status.name
     EXPIRED
 
-The question is moved to the EXPIRED state and the 'datelastresponse'
-attribute is updated to the message creation date.
+The question is moved to the EXPIRED state and the last response date is
+updated to the message creation date.
 
     >>> print question.status.name
     EXPIRED
@@ -376,8 +379,8 @@
     >>> print reopen_message.action.name
     REOPEN
 
-The question status is changed back to OPEN and the 'datelastquery'
-attribute is updated.
+The question status is changed back to OPEN and the last query date is
+updated.
 
     >>> print question.status.name
     OPEN
@@ -385,22 +388,22 @@
     True
 
 
-== 4) The question is invalid ==
+4) The question is invalid
+==========================
 
-Another scenario to handle is the case where the user posts a message
-that isn't really appropriate for the Answer Tracker like a SPAM
+In this scenario the user posts an inappropriate message, such as a spam
 message or a request for Ubuntu CDs.
 
     >>> spam_question = ubuntu.newQuestion(
     ...     no_priv, 'CDs', 'Please send 10 Ubuntu Dapper CDs.',
     ...     datecreated=now)
 
-The reject() method is used for such purpose. Only an answer contact,
-a product or distribution owner, or an administrator can reject a question.
+Such questions can be rejected by an answer contact, a product or distribution
+owner, or a Launchpad administrator.
 
-The canReject() method can be used to test if a user is allowed to
-reject the question. It takes as parameter the user who would reject the
-question:
+The canReject() method can be used to test if a user is allowed to reject the
+question.  While neither No Privileges Person nor Marilize are able to reject
+questions, Sample Person and the Ubuntu owner can.
 
     >>> spam_question.canReject(no_priv)
     False
@@ -413,7 +416,8 @@
     >>> spam_question.canReject(ubuntu.owner)
     True
 
-    # Administrator
+As a Launchpad administrator, so can Stub.
+
     >>> spam_question.canReject(stub)
     True
 
@@ -424,8 +428,7 @@
       ...
     Unauthorized: ...
 
-The reject() method takes a comment explaining the reason behind the
-rejection.
+When rejecting a question, a comment explaining the reason is given.
 
     >>> login('[e-mail]')
     >>> reject_message = spam_question.reject(
@@ -436,8 +439,8 @@
     >>> print reject_message.new_status.name
     INVALID
 
-After rejection, the question is marked as invalid and the
-'datelastresponse' attribute is updated.
+After rejection, the question is marked as invalid and the last response date
+is updated.
 
     >>> print spam_question.status.name
     INVALID
@@ -445,7 +448,7 @@
     True
 
 The rejection message is also considered as answering the message, so the
-date_solved, answerer and answer attributes are also updated.
+solution date, answerer, and answer are also updated.
 
     >>> spam_question.answer == reject_message
     True
@@ -454,23 +457,27 @@
     >>> spam_question.date_solved == now_plus_one_hour
     True
 
-== Other scenarios ==
-
-Many other scenarios are possible and some of those are probably more
-common than the ones we exposed. For example, it is likely that a user
-will answer directly a question (without asking for other
-information first). Or that the question user won't come back to confirm
-that an answer solved his problem. Another likely scenario is where
-the question will expire in the NEEDSINFO state when the question owner
-doesn't reply to the request for more information. All of these
-scenarios are covered by this API. It is not necessary to cover all
-these various possibilities here.
-(The ../interfaces/ftests/test_question_workflow.py functional test
-exercices all the various possible transitions.)
-
-== Changing the question status ==
-
-It is not possible to change the status attribute directly:
+
+Other scenarios
+===============
+
+Many other scenarios are possible and some are likely more common than others.
+For example, it is likely that a user will directly answer a question without
+asking for other information first.  Sometimes, the original questioner won't
+come back to confirm that an answer solved his problem.
+
+Another likely scenario is where the question will expire in the NEEDSINFO
+state because the question owner doesn't reply to the request for more
+information.  All of these scenarios are covered by this API, though it is not
+necessary to cover all these various possibilities here.  (The
+../tests/test_question_workflow.py functional test exercises all the various
+possible transitions.)
+
+
+Changing the question status
+============================
+
+It is not possible to change the status attribute directly.
 
     >>> login('[e-mail]')
     >>> question = ubuntu.newQuestion(**new_question_args)
@@ -479,10 +486,9 @@
       ...
     ForbiddenAttribute...
 
-A user which has launchpad.Admin permission on the question, can set the
-question status to an arbitrary value by using the setStatus() method.
-That method takes as parameters the new status and a comment explaining
-the status change.
+A user having launchpad.Admin permission on the question can set the question
+status to an arbitrary value, by giving the new status and a comment
+explaining the status change.
 
     >>> old_datelastquery = question.datelastquery
     >>> login(stub.preferredemail.email)
@@ -490,7 +496,7 @@
     ...      stub, QuestionStatus.INVALID, 'Changed status to INVALID',
     ...     datecreated=now_plus_one_hour)
 
-The method returns the IQuestionMessage recording the change:
+The method returns the IQuestionMessage recording the change.
 
     >>> print status_change_message.action.name
     SETSTATUS
@@ -499,7 +505,7 @@
     >>> print question.status.name
     INVALID
 
-The status change updates the datelastresponse attribute:
+The status change updates the last response date.
 
     >>> question.datelastresponse == now_plus_one_hour
     True
@@ -507,7 +513,7 @@
     True
 
 If an answer was present on the question, the status change also clears
-the answer and date_solved attributes.
+the answer and solution date.
 
     >>> msg = question.setStatus(stub, QuestionStatus.OPEN, 'Status change.')
     >>> answer_message = question.giveAnswer(sample_person, 'Install BootX.')
@@ -524,13 +530,13 @@
     ...     stub, QuestionStatus.OPEN, 'Reopen the question',
     ...     datecreated=now_plus_one_hour)
 
-    >>> question.date_solved is None
-    True
-    >>> question.answer is None
-    True
+    >>> print question.date_solved
+    None
+    >>> print question.answer
+    None
 
-But when the status is changed by a user who doesn't have the
-launchpad.Admin permission, an Unauthorized error is thrown:
+When the status is changed by a user who doesn't have the launchpad.Admin
+permission, an Unauthorized exception is thrown.
 
     >>> login('[e-mail]')
     >>> question.setStatus(sample_person, QuestionStatus.EXPIRED, 'Expire.')
@@ -538,10 +544,11 @@
       ...
     Unauthorized...
 
-== Adding Comments Without Changing the Status ==
-
-There is an addComment() method that can be use to add a message to the
-question without changing its status.
+
+Adding Comments Without Changing the Status
+===========================================
+
+Comments can be added to questions without changing the question's status.
 
     >>> login('[e-mail]')
     >>> old_status = question.status
@@ -556,8 +563,7 @@
     >>> comment.new_status == old_status
     True
 
-This method does not update the datelastresponse and datelastquery
-attributes.
+This method does not update the last response date or last query date.
 
     >>> question.datelastresponse == old_datelastresponse
     True
@@ -565,19 +571,20 @@
     True
 
 
-== Setting the question assignee ==
+Setting the question assignee
+=============================
 
 Users with launchpad.Moderator privileges, which are answer contacts,
 question target owners, and admins, can assign someone to answer a question.
 
-Sample Person is an answer contact for ubuntu. He can set the assignee.
+Sample Person is an answer contact for ubuntu, so he can set the assignee.
 
     >>> login('[e-mail]')
     >>> question.assignee = stub
     >>> print question.assignee.displayname
     Stuart Bishop
 
-Users without launchpad.Moderator privileges cannot set the assignee
+Users without launchpad.Moderator privileges cannot set the assignee.
 
     >>> login('[e-mail]')
     >>> question.assignee = sample_person
@@ -586,16 +593,18 @@
     Unauthorized: (<Question ...>, 'assignee', 'launchpad.Moderate')
 
 
-== Events ==
+Events
+======
 
 Each of the workflow methods will trigger a ObjectCreatedEvent for
 the message they create and a ObjectModifiedEvent for the question.
 
-    # Register an event listener that will print event it receives.
+    # Register an event listener that will print events it receives.
     >>> from lazr.lifecycle.interfaces import (
     ...     IObjectCreatedEvent, IObjectModifiedEvent)
-    >>> from canonical.launchpad.interfaces import IQuestion
-    >>> from canonical.launchpad.ftests.event import TestEventListener
+    >>> from lp.answers.interfaces.question import IQuestion
+    >>> from canonical.lazr.testing.event import TestEventListener
+
     >>> def print_event(object, event):
     ...     print "Received %s on %s" % (
     ...         event.__class__.__name__.split('.')[-1],
@@ -605,14 +614,15 @@
     >>> question_event_listener = TestEventListener(
     ...     IQuestion, IObjectModifiedEvent, print_event)
 
-Changing the status triggers the event:
+Changing the status triggers the event.
 
     >>> login(stub.preferredemail.email)
-    >>> msg = question.setStatus(stub, QuestionStatus.EXPIRED, 'Status change.')
+    >>> msg = question.setStatus(
+    ...     stub, QuestionStatus.EXPIRED, 'Status change.')
     Received ObjectCreatedEvent on QuestionMessage
     Received ObjectModifiedEvent on Question
 
-Example of a workflow method that triggers the events:
+Rejecting the question triggers the events.
 
     >>> msg = question.reject(stub, 'Close this question.')
     Received ObjectCreatedEvent on QuestionMessage
@@ -630,25 +640,28 @@
     >>> questionmessage_event_listener.unregister()
     >>> question_event_listener.unregister()
 
-== Reopenings ==
+
+Reopening the question
+======================
 
 Whenever a question considered answered (in the SOLVED or INVALID state)
 is reopened, a QuestionReopening is created.
 
-    # Let's register an event listener to notify us whenever a
-    # QuestionReopening is created.
-    >>> from canonical.launchpad.interfaces import IQuestionReopening
+    # Register an event listener to notify us whenever a QuestionReopening is
+    # created.
+    >>> from lp.answers.interfaces.questionreopening import IQuestionReopening
     >>> reopening_event_listener = TestEventListener(
     ...     IQuestionReopening, IObjectCreatedEvent, print_event)
 
 The most common use case is when a user confirms a solution, and then
-comes back to say that it doesn't work in fact.
+comes back to say that it doesn't, in fact, work.
 
     >>> login('[e-mail]')
     >>> question = ubuntu.newQuestion(**new_question_args)
     >>> answer_message = question.giveAnswer(
-    ...    sample_person, "You need some setup on the Mac side. "
-    ...    "Follow the instructions at "
+    ...     sample_person,
+    ...     "You need some setup on the Mac side. "
+    ...     "Follow the instructions at "
     ...     "https://help.ubuntu.com/community/Installation/OldWorldMacs",
     ...     datecreated=now_plus_one_hour)
     >>> confirm_message = question.confirmAnswer(
@@ -662,23 +675,23 @@
 
 The reopening record is available through the reopenings attribute.
 
-    >>> list(question.reopenings)
-    [<QuestionReopening...>]
-    >>> reopening = question.reopenings[0]
+    >>> reopenings = list(question.reopenings)
+    >>> len(reopenings)
+    1
+    >>> reopening = reopenings[0]
     >>> verifyObject(IQuestionReopening, reopening)
     True
 
-The reopening contain the date of the reopening in the datecreated
-attribute and the person who made the reopening in the reopener
-attribute.
+The reopening contain the date of the reopening, and the person who cause the
+reopening to happen.
 
     >>> reopening.datecreated == now_plus_three_hours
     True
     >>> print reopening.reopener.displayname
     No Privileges Person
 
-It contains the question prior answerer, datecreated, as well as the
-prior status in the priorstate attribute:
+It also contains the question's prior answerer, the date created, and the
+prior status of the question.
 
     >>> print reopening.answerer.displayname
     Sample Person
@@ -687,8 +700,8 @@
     >>> print reopening.priorstate.name
     SOLVED
 
-Another example of a reopening, would be when the question status is set
-back to OPEN after having been rejected.
+A reopening also occurs when the question status is set back to OPEN after
+having been rejected.
 
     >>> login('[e-mail]')
     >>> question = ubuntu.newQuestion(**new_question_args)
@@ -698,7 +711,8 @@
 
     >>> login(stub.preferredemail.email)
     >>> status_change_message = question.setStatus(
-    ...     stub, QuestionStatus.OPEN, 'Disregard previous rejection. '
+    ...     stub, QuestionStatus.OPEN,
+    ...     'Disregard previous rejection. '
     ...     'Sample Person was having a bad day.',
     ...     datecreated=now_plus_two_hours)
     Received ObjectCreatedEvent on QuestionReopening
@@ -718,7 +732,9 @@
     # Cleanup
     >>> reopening_event_listener.unregister()
 
-== Using an IMessage as Explanation ==
+
+Using an IMessage as an explanation
+===================================
 
 In all the workflow methods, it is possible to pass an IMessage instead of
 a string.
@@ -729,7 +745,7 @@
     >>> question = ubuntu.newQuestion(**new_question_args)
     >>> reject_message = messageset.fromText(
     ...     'Reject', 'Because I feel like it.', sample_person)
-    >>> question_message = question.reject(sample_person,reject_message)
+    >>> question_message = question.reject(sample_person, reject_message)
     >>> print question_message.subject
     Reject
     >>> print question_message.text_contents
@@ -737,7 +753,7 @@
     >>> question_message.rfc822msgid == reject_message.rfc822msgid
     True
 
-The IMessage owner must be the same than the person passed to the workflow
+The IMessage owner must be the same as the person passed to the workflow
 method.
 
     >>> login(stub.preferredemail.email)

=== modified file 'lib/lp/answers/interfaces/questionreopening.py'
--- lib/lp/answers/interfaces/questionreopening.py	2009-06-24 23:10:46 +0000
+++ lib/lp/answers/interfaces/questionreopening.py	2010-02-10 15:24:19 +0000
@@ -20,6 +20,7 @@
 from lp.answers.interfaces.question import IQuestion
 from lp.answers.interfaces.questionenums import QuestionStatus
 
+
 class IQuestionReopening(Interface):
     """A record of the re-opening of a question.