Document the differences between t.a.service.IService.disownServiceParent and t.a.service.IServiceCollection.removeService

[exarkun]

These methods do similar things, and it is not clear which is the correct way
to remove a service from a service collection.  I believe disownServiceParent is
the correct way.  This should be documented clearly.

[hypatia]

Thanks. As far as I can tell, all of the Service architecture needs far better docs.
Will likely get to this in a couple of weeks.

[hypatia]

Is removeService deprecated or does it have some internal use?

[exarkun]

<itamar> disownServiceParent is symmetric with setServiceParent in that it sets
the `parent' attribute on the child, so you probably want to use that and
`removeService' is the hook in the collection that subclasses can override, but
usually you don't call yourself.
It sounds like the code should stay the same and the docs should say something
like the above.

[hypatia]

Re-assigning doc bugs to edsuom.

[thijs]

(In [24555]) Branching to 'doc-diff-service-671'

[exarkun]

Mostly (but not entirely) trivial points:

• use C{} instead of '`
• symmetric is an adjective; the text should use symmetrically instead because it is modifying a verb (used) and so the adverb form is required.
• it doesn't make sense to talk about a subclass in the docstring for a method on an interface. it should talk about what an implementation would do, instead.
• control is non-specific; I think the docstring needs to talk about how an IServiceCollection needs to implement removeService to take a service out of the collection. It would also help if it explained that (perhaps by convention, only? I'm still not completely clear on the intent of the dual API is here) removeService is only responsible for cleaning up state on the IServiceCollection implementation. This is different from IService.disownServiceParent in that disownServiceParent implementations are required (or are they? does convention dictate this? I dunno) to call the IServiceCollection.removeService in addition to cleaning up any state on the IService itself (such as the parent attribute).

Perhaps it would be best to dispense with the text from itamar's suggestion entirely and just say something like Use this API to remove an IService from an IServiceCollection in the docstring for IService.disownServiceParent and something like Only implementations of IService.disownServiceParent should use this method. in the docstring of IServiceCollection.removeService.

[thijs]

Fixes in r25320, up for review.

[therve]

Great! Small cleanups:

• remove trailing whitespaces of the file
• I like to see a bit of indentation after epydoc fields, like this:

  @return: a L{Deferred} which is triggered when the service has
      finished shutting down. If shutting down is immediate, a value can
      be returned (usually, C{None}).
  

Then you can merge.

[thijs]

Replying to therve:

Great! Small cleanups: * remove trailing whitespaces of the file * I like to see a bit of indentation after epydoc fields, like this: @return: a L{Deferred} which is triggered when the service has finished shutting down. If shutting down is immediate, a value can be returned (usually, C{None}).

Addressed these points in r25376

[thijs]

(In [25377]) Merge doc-diff-service-671: Document the differences between t.a.service.IService.disownServiceParent and t.a.service.IServiceCollection.removeService.

Author: thijs Reviewer: exarkun, therve Fixes: #671