Ejemplo: Documentación Automática con ChatGPT

def generate_documentation(code_snippet):
    """
    Generates comprehensive documentation for code using AI.
    
    This function demonstrates how AI can analyze code structure,
    understand functionality, and create detailed documentation
    automatically, saving developers significant time.
    
    Args:
        code_snippet (str): The source code to document
        
    Returns:
        dict: Documentation structure containing:
            - summary: Brief description of functionality
            - parameters: Detailed parameter documentation  
            - returns: Return value documentation
            - examples: Usage examples
            - complexity: Time/space complexity analysis
            
    Example:
        >>> code = "def fibonacci(n): return n if n <= 1 else fibonacci(n-1) + fibonacci(n-2)"
        >>> doc = generate_documentation(code)
        >>> print(doc['summary'])
        'Recursive implementation of Fibonacci sequence calculation'
        
    Note:
        This function requires OpenAI API access for optimal results.
        For large codebases, consider batch processing to optimize costs.
    """
    import openai
    import ast
    import inspect
    
    try:
        # Parse code to understand structure
        parsed = ast.parse(code_snippet)
        
        # Extract function/class information
        functions = [node for node in ast.walk(parsed) if isinstance(node, ast.FunctionDef)]
        classes = [node for node in ast.walk(parsed) if isinstance(node, ast.ClassDef)]
        
        # Generate documentation using AI
        prompt = f"""
        Analyze this code and generate comprehensive documentation:
        
        {code_snippet}
        
        Please provide:
        1. Summary of functionality
        2. Parameter descriptions
        3. Return value documentation
        4. Usage examples
        5. Complexity analysis
        6. Potential edge cases
        """
        
        # AI-powered documentation generation
        response = openai.ChatCompletion.create(
            model="gpt-4",
            messages=[
                {"role": "system", "content": "You are an expert technical writer specializing in code documentation."},
                {"role": "user", "content": prompt}
            ],
            max_tokens=1500,
            temperature=0.3
        )
        
        documentation = {
            'summary': extract_summary(response.choices[0].message.content),
            'parameters': extract_parameters(response.choices[0].message.content),
            'returns': extract_returns(response.choices[0].message.content),
            'examples': extract_examples(response.choices[0].message.content),
            'complexity': extract_complexity(response.choices[0].message.content),
            'raw_response': response.choices[0].message.content
        }
        
        return documentation
        
    except Exception as e:
        return {
            'error': f"Documentation generation failed: {str(e)}",
            'fallback_doc': generate_basic_documentation(code_snippet)
        }

def extract_summary(ai_response):
    """Extract summary section from AI response"""
    lines = ai_response.split('\n')
    for i, line in enumerate(lines):
        if 'summary' in line.lower() or 'functionality' in line.lower():
            return lines[i+1].strip() if i+1 < len(lines) else ""
    return "Function documentation auto-generated by AI"

def extract_parameters(ai_response):
    """Extract parameter documentation from AI response"""
    # Implementation would parse parameter descriptions from AI response
    # This is a simplified version
    return "Parameters documented by AI analysis"

def extract_returns(ai_response):
    """Extract return value documentation from AI response"""
    return "Return values documented by AI analysis"

def extract_examples(ai_response):
    """Extract usage examples from AI response"""
    return "Usage examples generated by AI"

def extract_complexity(ai_response):
    """Extract complexity analysis from AI response"""
    return "Complexity analysis provided by AI"

def generate_basic_documentation(code_snippet):
    """Fallback documentation generator for when AI is unavailable"""
    return {
        'summary': "Basic documentation generated without AI",
        'note': "Consider using AI-powered documentation for better results"
    }

# Example usage
if __name__ == "__main__":
    sample_code = """
    def binary_search(arr, target):
        left, right = 0, len(arr) - 1
        while left <= right:
            mid = (left + right) // 2
            if arr[mid] == target:
                return mid
            elif arr[mid] < target:
                left = mid + 1
            else:
                right = mid - 1
        return -1
    """
    
    documentation = generate_documentation(sample_code)
    print("Generated Documentation:")
    print("-" * 50)
    for key, value in documentation.items():
        print(f"{key.upper()}: {value}")