I recently looked at using the ipaddress module in a project, and noticed some discrepencies between the code and the documentation, and some things that weren't documented.  A patch to fix these is attached.

* The IPv4Network.__init__ documentation wrongly claims that "/0.0.0.0"
  would be interpreted as a host mask i.e. "/32".  It's actually
  interpreted as a net mask, i.e. "/0".

* The IPv[46]Network.netmask property is not documented

* The IPv[46]Network.hostmask property is wrongly called "host mask"
  (with a space!) in the docs

* The IPv[46]Network.hostmask property is wrongly documented as a
  string but it's actually an IPv[46]Address

* The IPv6Network.__init__ documentation wrongly claims that a netmask
  can be specified, but this is not supported by the code.  The code
  only supports prefix lengths.

* The documentation should explain how network objects are ordered,
  since it's not obvious.

* The documentation should explain how interface objects are compared,
  both with other interface objects and with address objects, as it's
  not obvious.

* It's probably a good idea to document that you can't always pass a
  IPv4Interface object to a function that expects a IPv4Address.

* It would be nice to mention that address, network and interface objects
  are all hashable.

Kind regards,

Jon

(If this is accepted, please consider it for backport to 3.3 too.  It is just a documentation improvement).

Documentation fixes are always backported.

> * The IPv[46]Network.hostmask property is wrongly called "host mask"
>   (with a space!) in the docs

This one has already been fixed in 4f8ad9a4193f.

Thank you for the great patch Jon! :)

I rebased Jon's patch to current default with additional changes like fixing typos and markup tweaks. I also removed the following item since it doesn't seem to be crucial:

    * It's probably a good idea to document that you can't always pass a
      IPv4Interface object to a function that expects a IPv4Address.

Jon/Berker,

Are you interested in making a Github pull request for this?  Thanks!

Ahh, I also find some errors here in ipaddress doc and opened https://github.com/python/cpython/pull/6021 to fix them.

I've made a PR for Berker's patch.

New changeset 5609b78392d59c7362ef8aa5c4a4529325f01f27 by Xiang Zhang (Cheryl Sabella) in branch 'master':
 bpo-18802: Add more details to ipaddress documentation (GH-6083)
https://github.com/python/cpython/commit/5609b78392d59c7362ef8aa5c4a4529325f01f27

New changeset a323eee4c481c88f2b4030bbb224d9bc6bc14c9c by Miss Islington (bot) in branch '3.7':
bpo-18802: Add more details to ipaddress documentation (GH-6083)
https://github.com/python/cpython/commit/a323eee4c481c88f2b4030bbb224d9bc6bc14c9c

New changeset 481cbe8d6202658a7908d97f19f7e9e6061e3df3 by Miss Islington (bot) in branch '3.6':
bpo-18802: Add more details to ipaddress documentation (GH-6083)
https://github.com/python/cpython/commit/481cbe8d6202658a7908d97f19f7e9e6061e3df3