Docstrings feed directly into your API documentation. If you write good docstrings, you don't need redundant comments explaining what a function does; the docs handle that.
What does this function actually do?
What can go wrong when I use it?
Are there any gotchas I should know about?
Can I see a quick example?
This is basically like including Cockburn style use cases within the documentation (which in my opinion/experience is ideal)
Save inline comments for explaining why a specific Blender quirk exists (e.g., "We must update the scene here because Blender doesn't auto-refresh the viewport for this property"), etc
context - This is always bpy.types.Context.
strings - Anything in quotes "" or '' is str.
integers or floats - 13 is an integer 0.5 is a float
booleans - true or false
lists: Anything inside square brackets [ ] or created with [ ]
bpy objects - bpy.ops, bpy.context, bpy.data are specific Blender types
for #hints, you can just use Any or bpy.types if you import them.
Example of how this would look:
OP#08
import bpy
from typing import Any # Import this at the top
# Before:
def op8(context):
# ... code ...
# After (with hints):
def op8(context: bpy.types.Context) -> None:
# '-> None' means the function doesn't return a value
# ... code ...
Variables:
vertexratio = 0.995
# to :
vertexratio: float = 0.995
Purpose of this: helps VSCodium catch errors before you run the script. If you accidentally try to do math on a string, the editor will underline it in red. It also makes the code much easier to read for others (and future you). Maybe way more importantly, if anyone wants to fork, expand, use or view the file, they can understand exactly what everything does and/or has to be. It's crucial for sharing.
See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
Consider doing it the reStructuredText format for consistency.
Google-type docstring (very common) (but we would need to install napoleon not a problem)
https://medium.com/data-science/step-by-step-basics-code-autodocumentation-fa0d9ae4ac71
I think I'm going to add it just so that if someone is more familiar with that they're already set up to do it that way. It's not ideal to mix them but it's also a matter of keeping things accessible - they're both pretty human readable (and technically, people aren't reading that, they're reading the docs generated by it.
This also requires Ruff which is already in the conf.py ✓
Docstrings feed directly into your API documentation. If you write good docstrings, you don't need redundant comments explaining what a function does; the docs handle that.
What does this function actually do?
What can go wrong when I use it?
Are there any gotchas I should know about?
Can I see a quick example?
This is basically like including Cockburn style use cases within the documentation (which in my opinion/experience is ideal)
Save inline comments for explaining why a specific Blender quirk exists (e.g., "We must update the scene here because Blender doesn't auto-refresh the viewport for this property"), etc
context - This is always bpy.types.Context.
strings - Anything in quotes "" or '' is str.
integers or floats - 13 is an integer 0.5 is a float
booleans - true or false
lists: Anything inside square brackets [ ] or created with [ ]
bpy objects - bpy.ops, bpy.context, bpy.data are specific Blender types
for #hints, you can just use Any or bpy.types if you import them.
Example of how this would look:
OP#08
Variables:
Purpose of this: helps VSCodium catch errors before you run the script. If you accidentally try to do math on a string, the editor will underline it in red. It also makes the code much easier to read for others (and future you). Maybe way more importantly, if anyone wants to fork, expand, use or view the file, they can understand exactly what everything does and/or has to be. It's crucial for sharing.
See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
Consider doing it the reStructuredText format for consistency.
Google-type docstring (very common) (but we would need to install napoleon not a problem)
https://medium.com/data-science/step-by-step-basics-code-autodocumentation-fa0d9ae4ac71
I think I'm going to add it just so that if someone is more familiar with that they're already set up to do it that way. It's not ideal to mix them but it's also a matter of keeping things accessible - they're both pretty human readable (and technically, people aren't reading that, they're reading the docs generated by it.
This also requires Ruff which is already in the conf.py ✓