doc cleanup: minor corrections and improvements to docstrings + recent doc changes.
authorCampbell Barton <ideasman42@gmail.com>
Fri, 23 Mar 2012 01:55:38 +0000 (01:55 +0000)
committerCampbell Barton <ideasman42@gmail.com>
Fri, 23 Mar 2012 01:55:38 +0000 (01:55 +0000)
doc/python_api/rst/info_gotcha.rst
source/blender/makesrna/intern/rna_mesh.c

index 0a2918ca43c1dfdef80af1bf700a3a853c999eb9..1d94d68e15ef481f60594ef59145cebe5176d27c 100644 (file)
@@ -140,7 +140,7 @@ Since 2.63 NGons are supported, this adds some complexity since in some cases yo
 There are now 3 ways to access faces:
 
 * :class:`bpy.types.MeshPolygon` - this is the data stricture which now stores faces in object mode (access as ``mesh.polygons`` rather then ``mesh.faces``).
-* :class:`bpy.types.MeshTessFace` - the result of triangulating (tessellated) polygons, the main method of face access in 2.62 or older.
+* :class:`bpy.types.MeshTessFace` - the result of triangulating (tessellated) polygons, the main method of face access in 2.62 or older (access as ``mesh.tessfaces``).
 * :class:`bmesh.types.BMFace` - the polygons as used in editmode.
 
 For the purpose of the following documentation, these will be referred to as polygons, tessfaces and bmesh-faces respectively.
@@ -161,13 +161,18 @@ Support Overview
 +--------------+------------------------------+--------------------------------+--------------------------------+
 
 
+.. note::
+
+   Using the :mod:`bmesh` api is completely separate api from :mod:`bpy`, typically you would would use one or the other based on the level of editing needed, not simply for a different way to access faces.
+
+
 Creating
 --------
 
 All 3 datatypes can be used for face creation.
 
-* polygons are the most efficient way to create faces but the data structure is _very_ rigid and inflexible, you must have all your vertes and faces ready and create them all at once. This is further complicated by the fact that each polygon does not store its own verts (as with tessfaces), rather they reference an index and size in :class:`bpy.types.Mesh.loops` which in-turn is a fixed array.
-* tessfaces ideally should not be used for creating faces since they are really only tessellation cache of polygons, however for scripts upgrading from 2.62 this is by far the most straightforward option. This works by creating tessfaces and when finished - they can be converted into polygons by calling :class:`bpy.types.Mesh.update`. The obvious limitation is ngons cant be created this way.
+* polygons are the most efficient way to create faces but the data structure is _very_ rigid and inflexible, you must have all your vertes and faces ready and create them all at once. This is further complicated by the fact that each polygon does not store its own verts (as with tessfaces), rather they reference an index and size in :class:`bpy.types.Mesh.loops` which are a fixed array too.
+* tessfaces ideally should not be used for creating faces since they are really only tessellation cache of polygons, however for scripts upgrading from 2.62 this is by far the most straightforward option. This works by creating tessfaces and when finished - they can be converted into polygons by calling :class:`bpy.types.Mesh.update`. The obvious limitation is ngons can't be created this way.
 * bmesh-faces are most likely the easiest way for new scripts to create faces, since faces can be added one by one and the api has features intended for mesh manipulation. While :class:`bmesh.types.BMesh` uses more memory it can be managed by only operating on one mesh at a time.
 
 
@@ -195,7 +200,7 @@ Upgrading Importers from 2.62
 
 Importers can be upgraded to work with only minor changes.
 
-The main change to be made is used the tessellation versions of each function.
+The main change to be made is used the tessellation versions of each attribute.
 
 * mesh.faces --> :class:`bpy.types.Mesh.tessfaces`
 * mesh.uv_textures --> :class:`bpy.types.Mesh.tessface_uv_textures`
@@ -209,7 +214,7 @@ Upgrading Exporters from 2.62
 
 For exporters the most direct way to upgrade is to use tessfaces as with importing however its important to know that tessfaces may **not** exist for a mesh, the array will be empty as if there are no faces.
 
-So before accessing tessface data call: :class:`bmesh.types.BMesh.update` ``(calc_tessface=True)``.
+So before accessing tessface data call: :class:`bpy.types.Mesh.update` ``(calc_tessface=True)``.
 
 
 EditBones, PoseBones, Bone... Bones
index 6aa77d8c8d7e0b6a5c9f7ebaeb4814b43f629297..7eef6630924cfd38f47ae6408b00a7735e0aee45 100644 (file)
@@ -1443,7 +1443,7 @@ static void rna_def_mface(BlenderRNA *brna)
 
        srna = RNA_def_struct(brna, "MeshTessFace", NULL);
        RNA_def_struct_sdna(srna, "MFace");
-       RNA_def_struct_ui_text(srna, "Mesh Face", "Face in a Mesh datablock");
+       RNA_def_struct_ui_text(srna, "Mesh TessFace", "TessFace in a Mesh datablock");
        RNA_def_struct_path_func(srna, "rna_MeshTessFace_path");
        RNA_def_struct_ui_icon(srna, ICON_FACESEL);
 
@@ -2494,13 +2494,13 @@ static void rna_def_mesh(BlenderRNA *brna)
        prop = RNA_def_property(srna, "tessfaces", PROP_COLLECTION, PROP_NONE);
        RNA_def_property_collection_sdna(prop, NULL, "mface", "totface");
        RNA_def_property_struct_type(prop, "MeshTessFace");
-       RNA_def_property_ui_text(prop, "Faces", "Faces of the mesh");
+       RNA_def_property_ui_text(prop, "TessFaces", "Tessellation faces of the mesh (derived from polygons)");
        rna_def_mesh_faces(brna, prop);
 
        prop = RNA_def_property(srna, "loops", PROP_COLLECTION, PROP_NONE);
        RNA_def_property_collection_sdna(prop, NULL, "mloop", "totloop");
        RNA_def_property_struct_type(prop, "MeshLoop");
-       RNA_def_property_ui_text(prop, "Loops", "Loops of the mesh");
+       RNA_def_property_ui_text(prop, "Loops", "Loops of the mesh (polygon corners)");
        rna_def_mesh_loops(brna, prop);
 
        prop = RNA_def_property(srna, "polygons", PROP_COLLECTION, PROP_NONE);