347673 - nsIPipe.init could use better documentation

Status: RESOLVED INCOMPLETE

(Core :: XPCOM, enhancement, P5)

Description

[Jeff Walden [:Waldo]]

Documentation for nsIPipe.init is lacking.  Currently, most of the docs are implicit from the interface description, and while those docs are reasonable, they aren't sufficient.  If I'm implementing an interface or writing code that uses it, I'd prefer not to have to guess at expected behavior based on parameter names.  In particular the .init method needs information on "magic" values for its parameters:

- segmentAllocator can be (and probably usually would be) null
- creating pipes with "infinite" capacity
- segmentSize == 0 uses a default size
- a description of why and when you would want to set segmentSize to a
  non-default value, since the current description specifies nothing about the
  mechanics of the outputstream writing process (some of this may just be
  implicit stream knowledge I haven't yet gained, but that should make
  documenting it an even better idea)

Comment 1

[:Cykesiopka]

FWIW,
Bug 396069 added documentation that addresses all the above points, with the exception of:
  - a description of why and when [...]

Comment 2

[BugBot [:suhaib / :marco/ :calixte]]

The bug assignee is inactive on Bugzilla, so the assignee is being reset.

Comment 3

[Nika Layzell [:nika] (ni? for response)]

The interface here has changed enough in the last 16 years, that this bug isn't super relevant anymore.