py operators - don't use the screen as an operators ID anymore, screen's don't store operator instances and operator functions have access to the context if they need the current screen.

also add some more py api file descriptions.

source/blender/editors/interface/interface.c

@@ -766,7 +766,7 @@ static void ui_menu_block_set_keyaccels(uiBlock *block)
 {
 	uiBut *but;
 
-	unsigned int meny_key_mask= 0;
+	unsigned int menu_key_mask= 0;
 	unsigned char menu_key;
 	const char *str_pt;
 	int pass;
@@ -788,8 +788,8 @@ static void ui_menu_block_set_keyaccels(uiBlock *block)
 				if(but->str) {
 					for(str_pt= but->str; *str_pt; ) {
 						menu_key= tolower(*str_pt);
-						if((menu_key >= 'a' && menu_key <= 'z') && !(meny_key_mask & 1<<(menu_key-'a'))) {
-							meny_key_mask |= 1<<(menu_key-'a');
+						if((menu_key >= 'a' && menu_key <= 'z') && !(menu_key_mask & 1<<(menu_key-'a'))) {
+							menu_key_mask |= 1<<(menu_key-'a');
 							break;
 						}
 
@@ -816,7 +816,7 @@ static void ui_menu_block_set_keyaccels(uiBlock *block)
 					}
 
 					/* if all keys have been used just exit, unlikely */
-					if(meny_key_mask == (1<<26)-1) {
+					if(menu_key_mask == (1<<26)-1) {
 						return;
 					}
 				}

source/blender/makesrna/intern/rna_wm.c

@@ -821,7 +821,7 @@ static int operator_execute(bContext *C, wmOperator *op)
 	void *ret;
 	int result;
 
-	RNA_pointer_create(&CTX_wm_screen(C)->id, op->type->ext.srna, op, &opr);
+	RNA_pointer_create(NULL, op->type->ext.srna, op, &opr);
 	func= &rna_Operator_execute_func; /* RNA_struct_find_function(&opr, "execute"); */
 
 	RNA_parameter_list_create(&list, &opr, func);
@@ -847,7 +847,7 @@ static int operator_check(bContext *C, wmOperator *op)
 	void *ret;
 	int result;
 
-	RNA_pointer_create(&CTX_wm_screen(C)->id, op->type->ext.srna, op, &opr);
+	RNA_pointer_create(NULL, op->type->ext.srna, op, &opr);
 	func= &rna_Operator_check_func; /* RNA_struct_find_function(&opr, "check"); */
 
 	RNA_parameter_list_create(&list, &opr, func);
@@ -872,7 +872,7 @@ static int operator_invoke(bContext *C, wmOperator *op, wmEvent *event)
 	void *ret;
 	int result;
 
-	RNA_pointer_create(&CTX_wm_screen(C)->id, op->type->ext.srna, op, &opr);
+	RNA_pointer_create(NULL, op->type->ext.srna, op, &opr);
 	func= &rna_Operator_invoke_func; /* RNA_struct_find_function(&opr, "invoke"); */
 
 	RNA_parameter_list_create(&list, &opr, func);
@@ -899,7 +899,7 @@ static int operator_modal(bContext *C, wmOperator *op, wmEvent *event)
 	void *ret;
 	int result;
 
-	RNA_pointer_create(&CTX_wm_screen(C)->id, op->type->ext.srna, op, &opr);
+	RNA_pointer_create(NULL, op->type->ext.srna, op, &opr);
 	func= &rna_Operator_modal_func; /* RNA_struct_find_function(&opr, "modal"); */
 
 	RNA_parameter_list_create(&list, &opr, func);
@@ -923,7 +923,7 @@ static void operator_draw(bContext *C, wmOperator *op)
 	ParameterList list;
 	FunctionRNA *func;
 
-	RNA_pointer_create(&CTX_wm_screen(C)->id, op->type->ext.srna, op, &opr);
+	RNA_pointer_create(NULL, op->type->ext.srna, op, &opr);
 	func= &rna_Operator_draw_func; /* RNA_struct_find_function(&opr, "draw"); */
 
 	RNA_parameter_list_create(&list, &opr, func);
@@ -944,7 +944,7 @@ static int operator_cancel(bContext *C, wmOperator *op)
 	void *ret;
 	int result;
 
-	RNA_pointer_create(&CTX_wm_screen(C)->id, op->type->ext.srna, op, &opr);
+	RNA_pointer_create(NULL, op->type->ext.srna, op, &opr);
 	func= &rna_Operator_cancel_func; /* RNA_struct_find_function(&opr, "cancel"); */
 
 	RNA_parameter_list_create(&list, &opr, func);

source/blender/python/generic/bgl.c

@@ -1,5 +1,4 @@
-/* 
- *
+/*
  * ***** BEGIN GPL LICENSE BLOCK *****
  *
  * This program is free software; you can redistribute it and/or
@@ -21,20 +20,21 @@
  *
  * This is a new part of Blender.
  *
- * Contributor(s): Willian P. Germano
+ * Contributor(s): Willian P. Germano, Campbell Barton
  *
  * ***** END GPL LICENSE BLOCK *****
  */
 
 /** \file blender/python/generic/bgl.c
  *  \ingroup pygen
+ *
+ * This file is the 'bgl' module which wraps OpenGL functions and constants,
+ * allowing script writers to make OpenGL calls in their Python scripts.
+ *
+ * \note
+ * This module is very similar to 'PyOpenGL' which could replace 'bgl' one day.
  */
 
-
-/* This file is the 'bgl' module.
- * The BGL submodule "wraps" OpenGL functions and constants,
- * allowing script writers to make OpenGL calls in their Python scripts. */
-
 #include <Python.h>
 
 #include "bgl.h" /*This must come first */

source/blender/python/generic/bgl.h

@@ -1,5 +1,4 @@
-/* 
- *
+/*
  * ***** BEGIN GPL LICENSE BLOCK *****
  *
  * This program is free software; you can redistribute it and/or

source/blender/python/generic/blf_py_api.c

@@ -22,9 +22,10 @@
 
 /** \file blender/python/generic/blf_py_api.c
  *  \ingroup pygen
+ *
+ * This file defines the 'bgl' module, used for drawing text in OpenGL.
  */
 
-
 #include <Python.h>
 #include "blf_py_api.h"
 

source/blender/python/generic/bpy_internal_import.c

@@ -17,14 +17,19 @@
  *
  * This is a new part of Blender.
  *
- * Contributor(s): Willian P. Germano,
- *                 Campbell Barton
+ * Contributor(s): Willian P. Germano, Campbell Barton
  *
  * ***** END GPL LICENSE BLOCK *****
  */
 
 /** \file blender/python/generic/bpy_internal_import.c
  *  \ingroup pygen
+ *
+ * This file defines replacements for pythons '__import__' and 'imp.reload'
+ * functions which can import from blender textblocks.
+ *
+ * \note
+ * This should eventually be replaced by import hooks (pep 302).
  */
 
 

source/blender/python/generic/noise_py_api.c

@@ -1,8 +1,4 @@
 /*
- *
- * Blender.Noise BPython module implementation.
- * This submodule has functions to generate noise of various types.
- * 
  * ***** BEGIN GPL LICENSE BLOCK *****
  *
  * This program is free software; you can redistribute it and/or
@@ -24,13 +20,16 @@
  *
  * This is a new part of Blender.
  *
- * Contributor(s): eeshlo
+ * Contributor(s): eeshlo, Campbell Barton
  *
  * ***** END GPL LICENSE BLOCK *****
  */
 
 /** \file blender/python/generic/noise_py_api.c
  *  \ingroup pygen
+ *
+ * This file defines the 'noise' module, a general purpose module to access
+ * blenders noise functions.
  */
 
 

source/blender/python/generic/py_capi_utils.c

@@ -20,6 +20,13 @@
 
 /** \file blender/python/generic/py_capi_utils.c
  *  \ingroup pygen
+ *
+ * Extend upon CPython's API, filling in some gaps, these functions use PyC_
+ * prefix to distinguish them apart from CPython.
+ *
+ * \note
+ * This module should only depend on CPython, however it currently uses
+ * BLI_string_utf8() for unicode conversion.
  */
 
 

source/blender/python/intern/bpy_driver.c

@@ -23,7 +23,7 @@
 /** \file blender/python/intern/bpy_driver.c
  *  \ingroup pythonintern
  *
- * This file defines the 'BPY_driver_exec' to execute python drivers,
+ * This file defines the 'BPY_driver_exec' to execute python driver expressions,
  * called by the animation system, there are also some utility functions
  * to deal with the namespace used for driver execution.
  */

source/blender/python/intern/bpy_library.c

@@ -27,7 +27,8 @@
  * this would be done via RNA api but in this case a hand written python api
  * allows us to use pythons context manager (__enter__ and __exit__).
  *
- * Everything here is exposed via bpy.data.libraries.load(...) context manager.
+ * Everything here is exposed via bpy.data.libraries.load(...) which returns
+ * a context manager.
  */
 
 /* nifty feature. swap out strings for RNA data */
@@ -77,8 +78,8 @@ static PyObject *bpy_lib_dir(BPy_Library *self);
 
 static PyMethodDef bpy_lib_methods[]= {
 	{"__enter__", (PyCFunction)bpy_lib_enter, METH_NOARGS},
-	{"__exit__", (PyCFunction)bpy_lib_exit, METH_VARARGS},
-	{"__dir__", (PyCFunction)bpy_lib_dir, METH_NOARGS},
+	{"__exit__",  (PyCFunction)bpy_lib_exit,  METH_VARARGS},
+	{"__dir__",   (PyCFunction)bpy_lib_dir,   METH_NOARGS},
 	{NULL}           /* sentinel */
 };
 
@@ -289,7 +290,7 @@ static void bpy_lib_exit_warn_idname(BPy_Library *self, const char *name_plural,
 	PyObject *exc, *val, *tb;
 	PyErr_Fetch(&exc, &val, &tb);
 	if (PyErr_WarnFormat(PyExc_UserWarning, 1,
-						 "load: '%s' does not contain %s[\"%s\"]",
+	                     "load: '%s' does not contain %s[\"%s\"]",
 	                     self->abspath, name_plural, idname)) {
 		/* Spurious errors can appear at shutdown */
 		if (PyErr_ExceptionMatches(PyExc_Warning)) {
@@ -304,7 +305,7 @@ static void bpy_lib_exit_warn_type(BPy_Library *self, PyObject *item)
 	PyObject *exc, *val, *tb;
 	PyErr_Fetch(&exc, &val, &tb);
 	if (PyErr_WarnFormat(PyExc_UserWarning, 1,
-						 "load: '%s' expected a string type, not a %.200s",
+	                     "load: '%s' expected a string type, not a %.200s",
 	                     self->abspath, Py_TYPE(item)->tp_name)) {
 		/* Spurious errors can appear at shutdown */
 		if (PyErr_ExceptionMatches(PyExc_Warning)) {

source/blender/python/intern/bpy_util.c

@@ -27,7 +27,6 @@
  * use (unrelated to 'bpy.utils')
  */
 
-
 #include <Python.h>
 
 #include "bpy_util.h"