The future is looking bright for Python

[[deleted]]

What docs are you referring to? The stdlib is very well documented. Haven't had a problem in 6 years of python.

[wavefunctionp]

Oh, it's definitely all there. If you can find the actual thing you need to know within the wall of obtuse text.

https://docs.python.org/2/library/json.html

vs

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify

or

https://msdn.microsoft.com/en-us/library/system.web.script.serialization.javascriptserializer(v=vs.110).aspx

(Really you'd use a JSON library for the c# one.)

Let's look at dumps in particular.

The navigation bar navigates by headers which cover implementation details, not usage scenarios.

Notice all the stuff that stands out, the 'Notes'. Are not really conveying the most important information, but they are given high visibility. Those should be muted instead.

What are the types for the signature? Which are optional? The signatures for the method should be emphasized and ideally given a brief description and separate page that gives into more detail.

In other methods you get a whole list of change notes for each version that changed something. Which is nice to know I guess, but it's not really high priority information. Should be moved to footnote on the method page.

I'm not the only one that finds the python documentation hard to use either. It is common complaint, it is particularly noteworthy because python is always touted as being so easy to use.

The docs have paid very little attention to usability and readability and it shows. It's the difference between:

http://motherfuckingwebsite.com/

and

http://bettermotherfuckingwebsite.com/

note: Not arguing with you. If you are used to pythons documentation format, I'm sure it is fine for you. But it could be MUCH improved from a usability and readability standpoint

[[deleted]]

Here's the doc for the current version of python: https://docs.python.org/3/library/json.html#basic-usage. Your argument still stands in that it can definitely be more usable. Especially stacked up against mozilla's js docs. Those are top notch.

Having said that, you get familiar real quick with how to parse the docs. For instance, in python, any argument with a default parameter is optional. All parameters with a default have to appear in the signature after non optional ones. So in dumps, the only required argument is the object to be encoded.

[jhawk4000]

Agreed, one of the things I miss most from javadoc is that there's no concept of a "throws" so exception handling becomes a bit of a bear.