PyDoc: use complete sentences in comments for templates & examples

doc/python_api/rst/bgl.rst

@@ -902,12 +902,12 @@ including advanced features.
 
         import bgl
         xval, yval= 100, 40
-        # Get the scale of the view matrix
+        # Get the scale of the view matrix.
         view_matrix = bgl.Buffer(bgl.GL_FLOAT, 16)
         bgl.glGetFloatv(bgl.GL_MODELVIEW_MATRIX, view_matrix)
         f = 1.0 / view_matrix[0]
 
-        # Instead of the usual glRasterPos2i(xval, yval)
+        # Instead of the usual `glRasterPos2i(xval, yval)`.
         bgl.glRasterPos2f(xval * f, yval * f)
 
 

doc/python_api/rst/include__bmesh.rst

@@ -104,11 +104,11 @@ Here are some examples:
 
 .. code-block:: python
 
-   # in this example the active vertex group index is used,
-   # this is stored in the object, not the BMesh
+   # In this example the active vertex group index is used,
+   # this is stored in the object, not the `BMesh`.
    group_index = obj.vertex_groups.active_index
 
-   # only ever one deform weight layer
+   # Only ever one deform weight layer.
    dvert_lay = bm.verts.layers.deform.active
 
    for vert in bm.verts:

doc/python_api/rst/info_best_practice.rst

@@ -149,13 +149,13 @@ Rather than:
 
 .. code-block:: python
 
-   polygons = mesh.polygons[:]  # make a list copy of the meshes polygons
-   p_idx = len(polygons)     # Loop backwards
-   while p_idx:           # while the value is not 0
+   polygons = mesh.polygons[:]  # Make a list copy of the meshes polygons.
+   p_idx = len(polygons)        # Loop backwards
+   while p_idx:                 # While the value is not 0.
        p_idx -= 1
 
        if len(polygons[p_idx].vertices) == 3:
-           polygons.pop(p_idx)  # remove the triangle
+           polygons.pop(p_idx)  # Remove the triangle.
 
 
 It's faster to build a new list with list comprehension:
@@ -227,10 +227,10 @@ This works by swapping two list items, so the item you remove is always last:
 
    pop_index = 5
 
-   # swap so the pop_index is last.
+   # Swap so the pop_index is last.
    my_list[-1], my_list[pop_index] = my_list[pop_index], my_list[-1]
 
-   # remove last item (pop_index)
+   # Remove last item (pop_index).
    my_list.pop()
 
 
@@ -357,6 +357,6 @@ While developing a script it is good to time it to be aware of any changes in pe
    import time
    time_start = time.time()
 
-   # do something...
+   # Do something...
 
    print("My Script Finished: %.4f sec" % (time.time() - time_start))

doc/python_api/rst/info_gotchas_armatures_and_bones.rst

@@ -67,10 +67,10 @@ Examples using :class:`bpy.types.PoseBone` in Object or Pose-Mode:
 
 .. code-block:: python
 
-   # Gets the name of the first constraint (if it exists)
+   # Gets the name of the first constraint (if it exists).
    bpy.context.object.pose.bones["Bone"].constraints[0].name
 
-   # Gets the last selected pose bone (Pose-Mode only)
+   # Gets the last selected pose bone (Pose-Mode only).
    bpy.context.active_pose_bone
 
 

doc/python_api/rst/info_gotchas_crashes.rst

@@ -19,7 +19,7 @@ Here is an example of threading supported by Blender:
    def prod():
        print(threading.current_thread().name, "Starting")
 
-       # do something vaguely useful
+       # Do something vaguely useful.
        import bpy
        from mathutils import Vector
        from random import random
@@ -28,7 +28,7 @@ Here is an example of threading supported by Blender:
        print("Prodding", prod_vec)
        bpy.data.objects["Cube"].location += prod_vec
        time.sleep(random() + 1.0)
-       # finish
+       # Finish.
 
        print(threading.current_thread().name, "Exiting")
 
@@ -256,7 +256,7 @@ Only the reference to the data itself can be re-accessed, the following example
    bpy.ops.object.mode_set(mode='EDIT')
    bpy.ops.object.mode_set(mode='OBJECT')
 
-   # this will crash
+   # This will crash!
    print(polygons)
 
 
@@ -270,7 +270,7 @@ the following example shows how to avoid the crash above.
    bpy.ops.object.mode_set(mode='EDIT')
    bpy.ops.object.mode_set(mode='OBJECT')
 
-   # polygons have been re-allocated
+   # Polygons have been re-allocated.
    polygons = mesh.polygons
    print(polygons)
 
@@ -291,7 +291,7 @@ internally the array which stores this data is re-allocated.
    point = bpy.context.object.data.splines[0].bezier_points[0]
    bpy.context.object.data.splines[0].bezier_points.add()
 
-   # this will crash!
+   # This will crash!
    point.co = 1.0, 2.0, 3.0
 
 This can be avoided by re-assigning the point variables after adding the new one or by storing
@@ -315,9 +315,9 @@ The following example shows how this precaution works:
 .. code-block:: python
 
    mesh = bpy.data.meshes.new(name="MyMesh")
-   # normally the script would use the mesh here...
+   # Normally the script would use the mesh here.
    bpy.data.meshes.remove(mesh)
-   print(mesh.name)  # <- give an exception rather than crashing:
+   print(mesh.name)  # <- Give an exception rather than crashing:
 
    # ReferenceError: StructRNA of type Mesh has been removed
 
@@ -330,7 +330,7 @@ the next example will still crash:
    mesh = bpy.data.meshes.new(name="MyMesh")
    vertices = mesh.vertices
    bpy.data.meshes.remove(mesh)
-   print(vertices)  # <- this may crash
+   print(vertices)  # <- This may crash.
 
 
 Unfortunate Corner Cases

doc/python_api/rst/info_gotchas_internal_data_and_python_objects.rst

@@ -42,7 +42,7 @@ This can cause bugs when you add data (normally imported) then reference it late
 
    bpy.data.meshes.new(name=meshid)
 
-   # normally some code, function calls...
+   # Normally some code, function calls, etc.
    bpy.data.meshes[meshid]
 
 
@@ -52,7 +52,7 @@ Or with name assignment:
 
    obj.name = objname
 
-   # normally some code, function calls...
+   # Normally some code, function calls, etc.
    obj = bpy.data.meshes[objname]
 
 
@@ -69,15 +69,15 @@ this way you don't run this risk of referencing existing data from the blend-fil
 
 .. code-block:: python
 
-   # typically declared in the main body of the function.
+   # Typically declared in the main body of the function.
    mesh_name_mapping = {}
 
    mesh = bpy.data.meshes.new(name=meshid)
    mesh_name_mapping[meshid] = mesh
 
-   # normally some code, or function calls...
+   # Normally some code, or function calls, etc.
 
-   # use own dictionary rather than bpy.data
+   # Use own dictionary rather than `bpy.data`.
    mesh = mesh_name_mapping[meshid]
 
 
@@ -96,18 +96,18 @@ If you need to select between local and library data, there is a feature in ``bp
 
 .. code-block:: python
 
-   # typical name lookup, could be local or library.
+   # Typical name lookup, could be local or library.
    obj = bpy.data.objects["my_obj"]
 
-   # library object name look up using a pair
-   # where the second argument is the library path matching bpy.types.Library.filepath
+   # Library object name lookup using a pair,
+   # where the second argument is the library path matching bpy.types.Library.filepath.
    obj = bpy.data.objects["my_obj", "//my_lib.blend"]
 
-   # local object name look up using a pair
+   # Local object name look up using a pair,
    # where the second argument excludes library data from being returned.
    obj = bpy.data.objects["my_obj", None]
 
-   # both the examples above also works for 'get'
+   # Both the examples above also works for `get`.
    obj = bpy.data.objects.get(("my_obj", None))
 
 

doc/python_api/rst/info_overview.rst

@@ -362,7 +362,7 @@ For example, if you want to store material settings for a custom engine:
 
 .. code-block:: python
 
-   # Create new property
+   # Create new property:
    # bpy.data.materials[0].my_custom_props.my_float
    import bpy
 
@@ -389,7 +389,7 @@ For example, if you want to store material settings for a custom engine:
 
 .. code-block:: python
 
-   # Create new property group with a sub property
+   # Create new property group with a sub property:
    # bpy.data.materials[0].my_custom_props.sub_group.my_float
    import bpy
 
@@ -428,9 +428,9 @@ For example:
 
 .. code-block:: python
 
-   # add a new property to an existing type
+   # Add a new property to an existing type.
    bpy.types.Object.my_float: bpy.props.FloatProperty()
-   # remove
+   # Remove it.
    del bpy.types.Object.my_float
 
 This works just as well for ``PropertyGroup`` subclasses you define yourself.

doc/python_api/rst/info_quickstart.rst

@@ -182,7 +182,7 @@ This data is saved with the blend-file and copied with objects, for example:
    # which can have a fallback value.
    value = bpy.data.scenes["Scene"].get("test_prop", "fallback value")
 
-   # dictionaries can be assigned as long as they only use basic types.
+   # Dictionaries can be assigned as long as they only use basic types.
    collection = bpy.data.collections.new("MyTestCollection")
    collection["MySettings"] = {"foo": 10, "bar": "spam", "baz": {}}
 
@@ -363,10 +363,10 @@ so these are accessed as normal Python types.
 
   .. code-block:: python
 
-     # setting multiple snap targets
+     # Setting multiple snap targets.
      bpy.context.scene.tool_settings.snap_elements_base = {'VERTEX', 'EDGE'}
 
-     # passing as an operator argument for report types
+     # Passing as an operator argument for report types.
      self.report({'WARNING', 'INFO'}, "Some message!")
 
 
@@ -411,10 +411,10 @@ Example of a matrix, vector multiplication:
 
    .. code-block:: python
 
-      # modifies the Z axis in place.
+      # Modifies the Z axis in place.
       bpy.context.object.location.z += 2.0
 
-      # location variable holds a reference to the object too.
+      # Location variable holds a reference to the object too.
       location = bpy.context.object.location
       location *= 2.0