# Core


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

------------------------------------------------------------------------

### DocmentsCheckResult

``` python

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

``` python

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

``` python

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

``` python

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

```

*Check if function has return documentation*

------------------------------------------------------------------------

### count_todos_in_docs

``` python

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

``` python

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

``` python

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

``` python

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

``` python

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

``` python

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

``` python

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

``` python

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

``` python

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

```

*Check a specific notebook for docments compliance*

------------------------------------------------------------------------

### check_function

``` python

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

```

*Check a single function for docments compliance*

``` python
# 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

``` python
# 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=[])

``` python
# 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'])

``` python
# 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):

``` python
# 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