51–60 of 112 posts
We need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.
can i introduce you to my friend openCV? :/
I forget the specifics of how the example code worked but it acted as both a sender and receiver of DDE messages and did so by executing itself. I remember spending a good 30 minutes trying to work out how the example worked before giving up and doing the classic “let’s just run it and see what happens” approach.
The example code from Microsoft turned out to be a fork bomb and it quickly crashed my machine.
It took me a long time to trust Microsoft documentation again after that incident.
Seems that API documentation (in this case) is not terribly important to the bottom line :) (So why should the bother fixing it?)
We need a way to unit test documentation to see if the code snippets still compile and the things that are referenced still exist.
We do this for our project ( https://hail.is ) and it's a game changer. Saves so much time and so many bug reports.
Just an FYI. This is about Amazon's MWS API, which is Merchant Web Services, used to interact with the Amazon part of Amazon not the AWS side of Amazon. Also having working on an OSS Ruby library for it, and having to had work with it quite a bit, I can confirm. The MWS APIs leave a lot to be desired of, but they are an absolute gem compared to the Ebay APIs. My take on the problem is that these APIs were developed i…
Don't worry, the docs and APIs/libraries for AWS are just as bad Boto3 is eye-watering bad. Boto2 was written by someone with some knowledge of Python and usability. Boto3 is just "automatically generated" from their API It is not good. It is bad. The structure makes no sense. The API can be described as "the minimum that works".
Earlier quoted context omitted.
obligatory "Rust docs can do this"[0] (quite a nice feature tbh). [0] https://doc.rust-lang.org/rustdoc/documentation-tests.html
Python can too, and I think most other languages are inspired by it. https://docs.python.org/3/library/doctest.html
But yeah, Python made it usable :)
Earlier quoted context omitted.
I think you've explained the situation quite well. I got my career started helping a lot of big companies transition from SOAP/WSDL/XML tech to JSON APIs in the late 2000's (writing API servers and client libraries in PHP, Ruby, Python, and then Node.js) and so thought about these technologies day in and day out for many, many years. I think we are still missing a dead simpler way to do it all—a very basic Tree/Grid…
> Higher level types would be added onto that, but at the low level it's all about just keeping your data as simple and clean as possible. and at the end we would call it rpc and gave the binary protocol a better name, like protobuf or cap'n'proto?