Core

Core functionality for checking docments compliance

---

DocmentsCheckResult

def DocmentsCheckResult(
    name:str, type:str, notebook:str, has_docstring:bool, params_documented:Dict, return_documented:bool,
    missing_params:List, is_compliant:bool, source:str, has_todos:bool=False, todo_count:int=0,
    params_with_type_hints:Dict=None, return_has_type_hint:bool=False, params_missing_type_hints:List=None
)->None:

Result of checking a function/class for docments compliance

---

extract_param_docs_from_func

def extract_param_docs_from_func(
    func:Callable, # Function object to extract docs from
)->Dict: # Mapping of parameter names to their documentation

Extract parameter documentation from function object using fastcore.docments

---

extract_param_docs

def extract_param_docs(
    source:str, # Function source code
)->Dict: # Mapping of parameter names to their documentation

Extract parameter documentation from function source using docments style (fallback)

---

check_return_doc

def check_return_doc(
    source:str, # Function source code
)->bool: # Whether return is documented

Check if function has return documentation

---

count_todos_in_docs

def count_todos_in_docs(
    source:str, # Function/class source code
    name:str, # Name of the function/class for AST parsing
)->Tuple: # (todo_count, has_todos)

Count TODO placeholders only in documentation (docstring, param docs, return docs)

---

check_has_docstring_from_func

def check_has_docstring_from_func(
    func:Callable, # Function object to check
)->bool: # Whether the function has a docstring

Check if a function has a docstring using fastcore.docments

---

check_has_docstring

def check_has_docstring(
    source:str, # Function/class source code
    name:str, # Name of the function/class
)->bool: # Whether the definition has a docstring

Check if a function/class has a docstring using AST parsing (fallback)

---

function_has_return_value

def function_has_return_value(
    source:str, # Function source code
    name:str, # Function name
)->bool: # Whether function has explicit return statements with values

Check if a function actually returns a value (not just implicit None)

---

check_type_hints

def check_type_hints(
    definition:Dict, # Definition dict from scanner
    source:Optional=None, # Function source code (optional)
)->Tuple: # (params_with_type_hints, missing_type_hints, return_has_type_hint)

Check which parameters and return value have type hints

---

check_params_documentation

def check_params_documentation(
    definition:Dict, # Definition dict from scanner
    source:str, # Function source code
)->Tuple: # (params_documented, missing_params, return_documented)

Check parameter and return documentation for a function

---

determine_compliance

def determine_compliance(
    has_docstring:bool, # Whether definition has a docstring
    params_documented:Dict, # Which params have documentation
    return_documented:bool, # Whether return is documented
)->bool: # Overall compliance status

Determine if a definition is compliant based on documentation checks

---

check_definition

def check_definition(
    definition:Dict, # Definition dict from scanner
)->DocmentsCheckResult: # Check result with compliance details

Check a function/class definition for docments compliance

---

check_notebook

def check_notebook(
    nb_path:str, # Path to notebook file
)->None: # Prints compliance report

Check a specific notebook for docments compliance

---

check_function

def check_function(
    func:Callable, # Function object to check
)->DocmentsCheckResult: # Check result for the function

Check a single function for docments compliance

# Test checking a specific notebook
check_notebook("core.ipynb")

Checking core.ipynb:
📚 Docments Compliance Report
==================================================
Total definitions: 15
✅ Compliant: 15
❌ Non-compliant: 0


✅ Compliant definitions:
------------------------------

📓 core.ipynb:
  ✅ DocmentsCheckResult
  ✅ __post_init__
  ✅ extract_param_docs_from_func
  ✅ extract_param_docs
  ✅ check_return_doc
  ✅ count_todos_in_docs
  ✅ check_has_docstring_from_func
  ✅ check_has_docstring
  ✅ function_has_return_value
  ✅ check_type_hints
  ✅ check_params_documentation
  ✅ determine_compliance
  ✅ check_definition
  ✅ check_notebook
  ✅ check_function

# Test checking a function directly
def test_func(
    x: int,  # First number
    y: int = 0  # Second number  
) -> int:  # Sum of x and y
    "Add two numbers"
    return x + y

check_function(test_func)

✅ test_func is compliant

DocmentsCheckResult(name='test_func', type='FunctionDef', notebook='runtime', has_docstring=True, params_documented={'x': True, 'y': True}, return_documented=True, missing_params=[], is_compliant=True, source='def test_func(\n    x: int,  # First number\n    y: int = 0  # Second number  \n) -> int:  # Sum of x and y\n    "Add two numbers"\n    return x + y\n', has_todos=False, todo_count=0, params_with_type_hints={'x': True, 'y': True}, return_has_type_hint=True, params_missing_type_hints=[])

# Test with a non-compliant function
def bad_func(x, y):
    return x + y

check_function(bad_func)

❌ bad_func is not compliant
   - Missing docstring
   - Missing docs for: x, y
   - Missing type hints for: x, y
   - Missing return type hint

DocmentsCheckResult(name='bad_func', type='FunctionDef', notebook='runtime', has_docstring=False, params_documented={'x': False, 'y': False}, return_documented=True, missing_params=['x', 'y'], is_compliant=False, source='def bad_func(x, y):\n    return x + y\n', has_todos=False, todo_count=0, params_with_type_hints={'x': False, 'y': False}, return_has_type_hint=False, params_missing_type_hints=['x', 'y', 'return'])

# Test functions with and without return values
test_no_return = '''def function_no_return(x, y):
    "Print the sum but don't return anything"
    print(x + y)'''

test_explicit_none = '''def function_explicit_none(x, y):
    "Explicitly return None"
    print(x + y)
    return None'''

test_has_return = '''def function_has_return(x, y):
    "Return the sum"
    return x + y'''

test_conditional_return = '''def function_conditional_return(x, y):
    "Sometimes return a value"
    if x > 0:
        return x + y
    # Implicit None return when x <= 0'''

for source in [test_no_return, test_explicit_none, test_has_return, test_conditional_return]:
    # Extract function name from source
    import re
    name_match = re.search(r'def\s+(\w+)', source)
    if name_match:
        func_name = name_match.group(1)
        
        test_def = {
            'name': func_name,
            'type': 'FunctionDef',
            'source': source,
            'notebook': 'test.ipynb',
            'args': [{'name': 'x', 'annotation': None}, {'name': 'y', 'annotation': None}],
            'returns': None  # No return type annotation
        }
        
        result = check_definition(test_def)
        has_return = function_has_return_value(source, func_name)
        
        print(f"{func_name}:")
        print(f"  Has return value: {has_return}")
        print(f"  Missing type hints: {result.params_missing_type_hints}")
        print(f"  'return' in missing hints: {'return' in result.params_missing_type_hints}")
        print()

function_no_return:
  Has return value: False
  Missing type hints: ['x', 'y']
  'return' in missing hints: False

function_explicit_none:
  Has return value: False
  Missing type hints: ['x', 'y']
  'return' in missing hints: False

function_has_return:
  Has return value: True
  Missing type hints: ['x', 'y', 'return']
  'return' in missing hints: True

function_conditional_return:
  Has return value: True
  Missing type hints: ['x', 'y', 'return']
  'return' in missing hints: True

DeprecationWarning: ast.Str is deprecated and will be removed in Python 3.14; use ast.Constant instead
  isinstance(first_stmt.value, (ast.Str, ast.Constant))):
<ipython-input-1-1991b552406b>:32: DeprecationWarning: Attribute s is deprecated and will be removed in Python 3.14; use value instead
  if hasattr(first_stmt.value, 's'):
<ipython-input-1-1991b552406b>:33: DeprecationWarning: Attribute s is deprecated and will be removed in Python 3.14; use value instead
  docstring = first_stmt.value.s
<ipython-input-1-e268d0b51854>:15: DeprecationWarning: ast.Str is deprecated and will be removed in Python 3.14; use ast.Constant instead
  isinstance(node.body[0].value, (ast.Str, ast.Constant))):
<ipython-input-1-8d0cebd1f363>:20: DeprecationWarning: ast.NameConstant is deprecated and will be removed in Python 3.14; use ast.Constant instead
  elif isinstance(body_node.value, ast.NameConstant):

# Test refined TODO detection
test_cases = [
    # Case 1: TODOs only in documentation (should count)
    '''def func_with_doc_todos(
    x: int,  # TODO: Add description
    y: str  # TODO: Add description  
) -> bool:  # TODO: Add return description
    "TODO: Add function description"
    return True''',
    
    # Case 2: TODOs in function body but not docs (should NOT count)
    '''def func_with_code_todos(
    x: int,  # Parameter x
    y: str  # Parameter y
) -> bool:  # Returns boolean
    "Function with proper docs"
    # TODO: Implement this feature later
    todo_list = ["item1", "item2"]  # Variable named todo
    return True''',
    
    # Case 3: Mixed TODOs (should only count doc ones)
    '''def mixed_todos(
    x: int  # TODO: Add description
) -> bool:
    "Proper function description"
    # TODO: Refactor this code
    todo_items = []
    return True'''
]

for i, source in enumerate(test_cases, 1):
    test_def = {
        'name': f'test_func_{i}',
        'type': 'FunctionDef',
        'source': source,
        'notebook': 'test.ipynb',
        'args': [{'name': 'x', 'annotation': 'int'}],
        'returns': 'bool'
    }
    
    result = check_definition(test_def)
    print(f"Case {i}: {result.name}")
    print(f"  TODO count: {result.todo_count}")
    print(f"  Has TODOs: {result.has_todos}")
    print(f"  Compliant: {result.is_compliant}")
    print()

Case 1: test_func_1
  TODO count: 3
  Has TODOs: True
  Compliant: False

Case 2: test_func_2
  TODO count: 0
  Has TODOs: False
  Compliant: False

Case 3: test_func_3
  TODO count: 1
  Has TODOs: True
  Compliant: False