diff --git a/qrenderdoc/Code/pyrenderdoc/document_check.h b/qrenderdoc/Code/pyrenderdoc/document_check.h index f0dbf5e72..1946b4afe 100644 --- a/qrenderdoc/Code/pyrenderdoc/document_check.h +++ b/qrenderdoc/Code/pyrenderdoc/document_check.h @@ -26,6 +26,12 @@ inline void check_docstrings(swig_type_info **swig_types, size_t numTypes) { + // track all errors and fatal error at the end, so we see all of the problems at once instead of + // requiring rebuilds over and over. + // This does mean that e.g. a duplicated docstring could be reported multiple times but that's not + // the end of the world. + bool errors_found = false; + std::set docstrings; for(size_t i = 0; i < numTypes; i++) { @@ -46,29 +52,118 @@ inline void check_docstrings(swig_type_info **swig_types, size_t numTypes) snprintf(convert_error, sizeof(convert_error) - 1, "Duplicate docstring '%s' found on struct '%s' - are you missing a DOCUMENT()?", typedoc.c_str(), typeobj->tp_name); - RENDERDOC_LogMessage(LogType::Fatal, "QTRD", __FILE__, __LINE__, convert_error); + RENDERDOC_LogMessage(LogType::Error, "QTRD", __FILE__, __LINE__, convert_error); + errors_found = true; + } + + PyObject *dict = typeobj->tp_dict; + + // check the object's dict to see if this is an enum (or struct with constants). + // We require ALL constants be documented in a docstring with data:: directives + if(dict && PyDict_Check(dict)) + { + PyObject *keys = PyDict_Keys(dict); + + if(keys) + { + std::set constants; + + Py_ssize_t len = PyList_Size(keys); + for(Py_ssize_t i = 0; i < len; i++) + { + PyObject *key = PyList_GetItem(keys, i); + PyObject *value = PyDict_GetItem(dict, key); + + // if this key is a string (it should be) and the value is an integer, it's a constant + if(PyUnicode_Check(key) && PyLong_Check(value)) + { + char *str = NULL; + Py_ssize_t len = 0; + PyObject *bytes = PyUnicode_AsUTF8String(key); + PyBytes_AsStringAndSize(bytes, &str, &len); + + if(str == NULL || len == 0) + { + RENDERDOC_LogMessage(LogType::Error, "QTRD", __FILE__, __LINE__, convert_error); + errors_found = true; + } + else + { + constants.insert(std::string(str, str + len)); + } + + Py_DecRef(bytes); + } + } + + Py_DecRef(keys); + + if(!constants.empty()) + { + std::set documented; + + const char *docstring = typedoc.data(); + + const char identifier[] = ".. data::"; + + const char *datadoc = strstr(docstring, identifier); + + while(datadoc) + { + datadoc += sizeof(identifier) - 1; + + while(isspace(*datadoc)) + datadoc++; + + const char *eol = strchr(datadoc, '\n'); + + if(!eol) + break; + + documented.insert(std::string(datadoc, eol)); + + datadoc = strstr(datadoc, identifier); + } + + for(auto it = constants.begin(); it != constants.end(); ++it) + { + // allow enums with First or Count members to be undocumented + if(*it == "First" || *it == "Count") + continue; + + if(documented.find(*it) == documented.end()) + { + snprintf(convert_error, sizeof(convert_error) - 1, + "'%s::%s' is not documented in class docstring", typeobj->tp_name, + it->c_str()); + RENDERDOC_LogMessage(LogType::Error, "QTRD", __FILE__, __LINE__, convert_error); + errors_found = true; + } + } + } + } } PyMethodDef *method = typeobj->tp_methods; while(method->ml_doc) { - std::string typedoc = method->ml_doc; + std::string method_doc = method->ml_doc; size_t i = 0; - while(typedoc[i] == '\n') + while(method_doc[i] == '\n') i++; // skip the first line as it's autodoc generated - i = typedoc.find('\n', i); + i = method_doc.find('\n', i); if(i != std::string::npos) { - while(typedoc[i] == '\n') + while(method_doc[i] == '\n') i++; - typedoc.erase(0, i); + method_doc.erase(0, i); - result = docstrings.insert(typedoc); + result = docstrings.insert(method_doc); if(!result.second) { @@ -76,11 +171,16 @@ inline void check_docstrings(swig_type_info **swig_types, size_t numTypes) convert_error, sizeof(convert_error) - 1, "Duplicate docstring '%s' found on method '%s.%s' - are you missing a DOCUMENT()?", method_doc.c_str(), typeobj->tp_name, method->ml_name); - RENDERDOC_LogMessage(LogType::Fatal, "QTRD", __FILE__, __LINE__, convert_error); + RENDERDOC_LogMessage(LogType::Error, "QTRD", __FILE__, __LINE__, convert_error); + errors_found = true; } } method++; } } + + if(errors_found) + RENDERDOC_LogMessage(LogType::Critical, "QTRD", __FILE__, __LINE__, + "Found errors in python binding docstrings. Please fix!"); }