121–130 of 179 posts
Earlier quoted context omitted.
> £JOB Wait a second, do people use $ for `$job` because it's how they earn money and not, as I've always thought, used it as a variable name? Stop throwing my entire world view out of order please.
The $ is for variables. And the upper case make it a BASIC variable, instead of something like Perl or PHP. Some times people put it in angle brackets . I have no idea what system use variables like that.
Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function. Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I nee…
This is the right answer. Everyone who disagrees with you are amateurs. A Javadoc-esque API doc is the minimum requirement for a serious language/library. Examples and tutorials are nice too, but the API doc can be automatically generated in every serious language so not having it is just plain unacceptable. Tutorials, articles and examples etc are fine too, they can be combined with the API doc like Java does. But t…
"No true Scotsman would want examples."
I'm far from an amateur and I want to see several concise examples in documentation. That doesn't mean that's all I want to see.
Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function. Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I nee…
Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both .
[0] https://www.man7.org/linux/man-pages/man1/man.1.html#DESCRIP...
Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function. Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I nee…
Personally - what you're asking for is type definitions. And it's a blurry line, since type definitions are a good form of documentation. It's just that type-system tooling has mostly replaced the need to go read through the docs for that. I expect to get it easily and obviously in whatever editor or IDE I've configured. I think the prevalence of example based documentation is because of this trend - don't waste time…
With python, it could be a mysterious class that isn't explicitly mentioned.
For Rust, you often need to know 4 layers deep of nested types for various error and flow control, and once generics are introduced with the expectation of implemented traits, it all goes out the window.
If I need to declare the type of a value ahead of time, or know it's shape to serialize, check, etc, I want a very clear "this is what it returns, this is how it's expected to be used".
They are not the “best.” They are helpful. I am tired of rudimentary docs that only have examples.
Given the choice between massive, "complete" documentation with no examples and decent but incomplete docs with good examples, I’ll pick the second every time. Why? Because if you don’t explain how to actually use something, all the fine-grained details are pointless. Classic example: try looking up the Java docs around 2003–2005 to figure out how to display an image in a Swing application. Endless pages about Graphi…
[0] https://fizyka.umk.pl/~jacek/docs/javatutorial/uiswing/compo...
Earlier quoted context omitted.
This is the right answer. Everyone who disagrees with you are amateurs. A Javadoc-esque API doc is the minimum requirement for a serious language/library. Examples and tutorials are nice too, but the API doc can be automatically generated in every serious language so not having it is just plain unacceptable. Tutorials, articles and examples etc are fine too, they can be combined with the API doc like Java does. But t…
> You optimize for power users not amateurs. Sure, but you can optimize for one without excluding the other. Adding examples _allows_ amateurs to gain experience and _become_ power user, and imposes near-zero cost on power users who can just skip a couple lines and get into the "real" API doc.
Earlier quoted context omitted.
This is the right answer. Everyone who disagrees with you are amateurs. A Javadoc-esque API doc is the minimum requirement for a serious language/library. Examples and tutorials are nice too, but the API doc can be automatically generated in every serious language so not having it is just plain unacceptable. Tutorials, articles and examples etc are fine too, they can be combined with the API doc like Java does. But t…
Everyone who disagrees with you are amateurs. "No true Scotsman would want examples." I'm far from an amateur and I want to see several concise examples in documentation. That doesn't mean that's all I want to see.
They're not the best. The best is thorough api docs. The rest is nice to have.
And I'm not no true scotsmaning, I'm just saying most devs are ass. I know, I see people with 20 years of experience on me write buggy trash code that I have to fix. I see people whine about the java docs as if they aren't some of the best damn docs available anywhere. Because they're ass and they can't properly use the tools they're given. They'd rather have examples and copy snippets from SO or have ChatGPT write it for them.
Any professional will appreciate proper documentation. It is literally impossible to create examples for every situation. Api docs, by their nature, cover all use cases because they simply describe what exists not how to use it. So for those of us with the knowledge and intelligence to actually just look at the parts and put them together on our own, ie professionals, API docs are king. Examples are useful sometime, API docs are useful all the time.
But of course if you don't even know the language well enough to read the documentation, you prefer examples.
Radical opinion: If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, the method is probably trying to do too many things. In particular, I don't want to have to learn half a dozen footguns because of a leaky abstraction.
No. Examples are there to show how to use this method, and other methods in conjunction. You can intuit all you want from a method signature, and then you will fail to produce working code because you missed a config, or a preparation step, or don't understand how to process the results, or...
If you have a `Foo` object, it should always be able to do every possible thing a `Foo` can do.
If you need to do something first, it should be a required argument to whatever lets you construct a `Foo` in the first place.
We advise developers to include examples in their documentation, often under their own ## Examples heading. To ensure examples do not get out of date, Elixir's test framework (ExUnit) provides a feature called doctests that allows developers to test the examples in their documentation.
Doctests work by parsing out code samples starting with iex> from the documentation. You can read more about them at ExUnit.DocTest.