mirror of
https://github.com/github/codeql.git
synced 2026-05-25 00:27:09 +02:00
a276f721f7
This one also allows easy access to the method being overridden and the class on which it resides. This let's us simplify DocStrings.ql accordingly.
52 lines
1.4 KiB
Plaintext
52 lines
1.4 KiB
Plaintext
/**
|
|
* @name Missing docstring
|
|
* @description Omitting documentation strings from public classes, functions or methods
|
|
* makes it more difficult for other developers to maintain the code.
|
|
* @kind problem
|
|
* @tags maintainability
|
|
* readability
|
|
* @problem.severity recommendation
|
|
* @sub-severity low
|
|
* @precision medium
|
|
* @id py/missing-docstring
|
|
*/
|
|
|
|
/*
|
|
* NOTE: precision of 'medium' reflects the lack of precision in the underlying rule.
|
|
* Do we care whether a function has a docstring? That often depends on the reader of that docstring.
|
|
*/
|
|
|
|
import python
|
|
private import semmle.python.dataflow.new.internal.DataFlowDispatch
|
|
|
|
predicate needs_docstring(Scope s) {
|
|
s.isPublic() and
|
|
(
|
|
not s instanceof Function
|
|
or
|
|
function_needs_docstring(s)
|
|
)
|
|
}
|
|
|
|
predicate function_needs_docstring(FunctionMetrics f) {
|
|
not exists(Function base |
|
|
DuckTyping::overridesMethod(f, _, base) and
|
|
not function_needs_docstring(base)
|
|
) and
|
|
f.getName() != "lambda" and
|
|
(f.getNumberOfLinesOfCode() - count(f.getADecorator())) > 2 and
|
|
not DuckTyping::isPropertyAccessor(f)
|
|
}
|
|
|
|
string scope_type(Scope s) {
|
|
result = "Module" and s instanceof Module and not s.(Module).isPackage()
|
|
or
|
|
result = "Class" and s instanceof Class
|
|
or
|
|
result = "Function" and s instanceof Function
|
|
}
|
|
|
|
from Scope s
|
|
where needs_docstring(s) and not exists(s.getDocString())
|
|
select s, scope_type(s) + " " + s.getName() + " does not have a docstring."
|