source/blender/blenkernel/BKE_mesh.h

@@ -323,16 +323,14 @@ void BKE_mesh_recalc_looptri(const struct MLoop *mloop,
 /* *** mesh_normals.cc *** */
 
 /**
- * Returns the normals for each vertex, which is defined as the weighted average of the normals
+ * See #Mesh::vert_normals().
- * from a vertices surrounding faces, or the normalized position of vertices connected to no faces.
+ * \warning May return null if the mesh is empty.
- * \warning May still return null if the mesh is empty.
  */
 const float (*BKE_mesh_vert_normals_ensure(const struct Mesh *mesh))[3];
 
 /**
- * Return the normal direction of every polygon, which is defined by the winding direction of its
+ * See #Mesh::poly_normals().
- * corners.
+ * \warning May return null if the mesh is empty or has no polygons.
- * \warning May still return null if the mesh is empty or has no polygons.
  */
 const float (*BKE_mesh_poly_normals_ensure(const struct Mesh *mesh))[3];
 

source/blender/blenkernel/intern/mesh_normals.cc

@@ -100,7 +100,6 @@ static void add_v3_v3_atomic(float r[3], const float a[3])
  * Related to managing normals but not directly related to calculating normals.
  * \{ */
 
-
 float (*BKE_mesh_vert_normals_for_write(Mesh *mesh))[3]
 {
   if (mesh->runtime->vert_normals == nullptr) {

source/blender/makesdna/DNA_mesh_types.h

@@ -279,13 +279,12 @@ typedef struct Mesh {
   void loose_edges_tag_none() const;
 
   /**
-   * Normal direction of every polygon, which is defined by the winding direction of its corners.
+   * Normal direction of polygons, defined by positions and the winding direction of face corners.
    */
   blender::Span<blender::float3> poly_normals() const;
   /**
-   * Normal direction for each vertex, which is defined as the weighted average of the normals
+   * Normal direction of vertices, defined as the weighted average of face normals
-   * from a vertices surrounding faces, or the normalized position of vertices connected to no
+   * surrounding each vertex and the normalized position for loose vertices.
-   * faces.
    */
   blender::Span<blender::float3> vert_normals() const;
 #endif