Coding 2025-09-15
I'm getting an early start on the entry today, because writing the entry means I have to work on a project to have something to write about. Anyway, here we go, documentation.
Python docstrings are stored exactly as they are represented in source code, and, if I recall correctly, reformatted as part of displaying help. This means that all of the __doc__ attributes I'm working with will have a trailing line of all whitespace, with no newline at the end. And a leading line with no indentation, and, because I'm generating method documentation, the remaining lines start at eight spaces worth of indentation.
Now, consider the parts of the docstring:
- Short description
- Long description
- Parameter and return documentation
So, the parameter and return documentation should be on the "template" docstring, which should also contain the short description. Thinking more about the short description, I thought I wanted the name to be templated in, but I changed my mind. (Not putting the class names back.) This means I don't need to worry about the kinding helpers, and can focus on the typing code.
I want the private implementation functions to just provide the long description. If the implementations start with a blank line, have another blank line, and then the long description, then the "template" can simply interpolate the implementation documentation at the end of the first line, before the newline. Checking the behavior of strings when I copy and paste around, the final blank line of the implementation should be removed. (I suppose unless the template doesn't contain a newline, but it... should.)
All right, I've written a helper function to interleave all of this stuff properly. Now, I need to work out the "right" way to deep copy a function so I can give it a new docstring.
...
I found something on StackOverflow; it's probably fine.
The tests still pass, at least, although I did need to shove a bunch of typing ignores in.
Anyway, I figured I'd try to grind through the lint errors for a bit, and I need to ponder some of them before I move on, so I'm going to wind down for now and see what I think when I get back to it.
Good night.