Issue #3080: document encoding used by import functions

1 files changed, 45 insertions, 14 deletions

diff --git a/Include/import.h b/Include/import.h
index 2df94ff11c..400e97cefe 100644
--- a/Include/import.h
+++ b/Include/import.h
@@ -9,26 +9,49 @@ extern "C" {
 
 PyAPI_FUNC(long) PyImport_GetMagicNumber(void);
 PyAPI_FUNC(const char *) PyImport_GetMagicTag(void);
-PyAPI_FUNC(PyObject *) PyImport_ExecCodeModule(char *name, PyObject *co);
+PyAPI_FUNC(PyObject *) PyImport_ExecCodeModule(
+    char *name,                 /* UTF-8 encoded string */
+    PyObject *co
+    );
 PyAPI_FUNC(PyObject *) PyImport_ExecCodeModuleEx(
-	char *name, PyObject *co, char *pathname);
+    char *name,                 /* UTF-8 encoded string */
+    PyObject *co,
+    char *pathname              /* decoded from the filesystem encoding */
+    );
 PyAPI_FUNC(PyObject *) PyImport_ExecCodeModuleWithPathnames(
-	char *name, PyObject *co, char *pathname, char *cpathname);
+    char *name,                 /* UTF-8 encoded string */
+    PyObject *co,
+    char *pathname,             /* decoded from the filesystem encoding */
+    char *cpathname             /* decoded from the filesystem encoding */
+    );
 PyAPI_FUNC(PyObject *) PyImport_GetModuleDict(void);
-PyAPI_FUNC(PyObject *) PyImport_AddModule(const char *name);
-PyAPI_FUNC(PyObject *) PyImport_ImportModule(const char *name);
-PyAPI_FUNC(PyObject *) PyImport_ImportModuleNoBlock(const char *);
-PyAPI_FUNC(PyObject *) PyImport_ImportModuleLevel(char *name,
-	PyObject *globals, PyObject *locals, PyObject *fromlist, int level);
+PyAPI_FUNC(PyObject *) PyImport_AddModule(
+    const char *name            /* UTF-8 encoded string */
+    );
+PyAPI_FUNC(PyObject *) PyImport_ImportModule(
+    const char *name            /* UTF-8 encoded string */
+    );
+PyAPI_FUNC(PyObject *) PyImport_ImportModuleNoBlock(
+    const char *name            /* UTF-8 encoded string */
+    );
+PyAPI_FUNC(PyObject *) PyImport_ImportModuleLevel(
+    char *name,                 /* UTF-8 encoded string */
+    PyObject *globals,
+    PyObject *locals,
+    PyObject *fromlist,
+    int level
+    );
 
 #define PyImport_ImportModuleEx(n, g, l, f) \
-	PyImport_ImportModuleLevel(n, g, l, f, -1)
+    PyImport_ImportModuleLevel(n, g, l, f, -1)
 
 PyAPI_FUNC(PyObject *) PyImport_GetImporter(PyObject *path);
 PyAPI_FUNC(PyObject *) PyImport_Import(PyObject *name);
 PyAPI_FUNC(PyObject *) PyImport_ReloadModule(PyObject *m);
 PyAPI_FUNC(void) PyImport_Cleanup(void);
-PyAPI_FUNC(int) PyImport_ImportFrozenModule(char *);
+PyAPI_FUNC(int) PyImport_ImportFrozenModule(
+    char *name                  /* UTF-8 encoded string */
+    );
 
 #ifndef Py_LIMITED_API
 #ifdef WITH_THREAD
@@ -41,9 +64,14 @@ PyAPI_FUNC(int) _PyImport_ReleaseLock(void);
 
 PyAPI_FUNC(void) _PyImport_ReInitLock(void);
 
-PyAPI_FUNC(PyObject *)_PyImport_FindBuiltin(char *);
+PyAPI_FUNC(PyObject *)_PyImport_FindBuiltin(
+    char *name                  /* UTF-8 encoded string */
+    );
 PyAPI_FUNC(PyObject *)_PyImport_FindExtensionUnicode(char *, PyObject *);
-PyAPI_FUNC(int)_PyImport_FixupBuiltin(PyObject*, char *);
+PyAPI_FUNC(int)_PyImport_FixupBuiltin(
+    PyObject *mod,
+    char *name                  /* UTF-8 encoded string */
+    );
 PyAPI_FUNC(int)_PyImport_FixupExtensionUnicode(PyObject*, char *, PyObject *);
 
 struct _inittab {
@@ -56,11 +84,14 @@ PyAPI_FUNC(int) PyImport_ExtendInittab(struct _inittab *newtab);
 
 PyAPI_DATA(PyTypeObject) PyNullImporter_Type;
 
-PyAPI_FUNC(int) PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void));
+PyAPI_FUNC(int) PyImport_AppendInittab(
+    const char *name,           /* ASCII encoded string */
+    PyObject* (*initfunc)(void)
+    );
 
 #ifndef Py_LIMITED_API
 struct _frozen {
-    char *name;
+    char *name;                 /* ASCII encoded string */
     unsigned char *code;
     int size;
 };