Exceptions information in documentation

[TravisJoe]

I find it quite nice to see in documentation the possible exceptions. This makes writing exception handling much easier especially on cases harder to simulate. I know I can dig deeper into the code to see what might happen, but I feel it would really round out the documentation and help save me a lot of time.

I know this potentially a lot of work and willing to contribute funds to help pay for this.

[adritium]

When I asked for documentation on the C-code design, I was told

I think I mentioned this before, but here it is again: such documentation of internals is not needed and hence makes no sense. In my opinion.
It is not needed because the most of the MicroPython code is particularly well written and readable and has comments where needed.

I'll concede that documenting the internal design is different from exceptions which are an external interface but the basic attitude is that documentation is not high priority.

And it's not without reason.
Sort the issues by date and you'll see plenty of functional changes >12 months old that are unimplemented.

From a core contributor:

It so happens that I was looking at it these days too, and of course I'd like to implement detailed dumper, then assembler (builder) for .mpy, then as much as possible of "dis" module for micropython-lib, but those are just a few of dozens of tasks I have in queue, so it will be months if not years.

[TravisJoe]

I figured there are so much going on, and open source projects rarely have funds to hire people to just work on secondary concerns. But I also see as documentation grows the harder it will be to start adding these types of notes.

To me exception notes in the Micropython documentation bridges C code and micropython. I deal with exception handling in my pure micropython code all the time, but sometimes I do not know what exceptions might be thrown by the API until I have one.

A generic example is I was writing some I2C library and due to a solder issue I got an exception from a timeout. Based on the documentation I did not know for certain that might happen. I know timeout is a general exception to handle, but it would be nice to at least see the documentation confirm it will happen and which one to catch.

I am wondering if I/we could setup some funding methods for these types of updates that might not get as much attention until you know they exist. I am the type of person that would not mind "subscribing" to monthly, quarterly or yearly donations to projects like micropython because I use them for work applications. That is easier than lump sums for me. But I would also like to know that if I pay some of my request become priority. Anyways, that is a different conversation.

[adritium]

Well let me make it clear: I’m not even a code contributor let alone in charge of this project.

If you’re willing to contribute any $, contact @dpgeorge @pfalcon directly.

My post was to offer my experience working with micropython for one year exactly.

[pfalcon]

Who said docs are not needed? Of course they're needed! Feel free to write them, then maintain over time. You can't even imagine what difference it can make in 2-3 years, even if working on it just once a week!

[pfalcon]

@TravisJoe : The situation with exceptions when calling functions which access hardware or OS services is very simple: any of them can throw OSError. Which one actually throws, and which possible error numbers - that's MicroPython port dependent.

As you can see, everything is simple, and even - post-factum - obvious. Yes, it would be nice if it was written in the docs. Writing it once won't help, as people won't read it there. So, it should be sprinkled around. Which is indeed not a kind of activity which someone does for fun, more reminds of something your boss tells you to do at dayjob.