A Hybrid Neural-Symbolic Framework for Reliable Automated Source Code Documentation

Abstract

Inadequate code documentation is a persistent challenge in software development. Time constraints often lead developers to neglect commenting, resulting in poorly documented codebases. This undermines knowledge sharing, reduces maintainability, and weakens team collaboration. Over time, such neglect erodes software sustainability, as critical knowledge becomes confined to individual developers rather than embedded within the code itself. This study presents CodeSage, an automated system for generating inline code comments and docstrings via a retrieval-augmented architecture. CodeBERT (125M parameters) retrieves semantically similar examples from a FAISS index of 50,000 code-documentation pairs, while CodeT5 (220M parameters) generates natural language documentation. A modular parser supports five languages: Python, JavaScript, TypeScript, Java, and C++. Evaluation used BLEU, ROUGE-L, METEOR, and BERTScore on 80 Python code-comment pairs from CodeSearchNet, alongside human evaluation across four quality criteria. The system achieved a BERTScore F1 of 0.7748, METEOR of 0.2978, ROUGE-L of 0.2585, and BLEU of 0.1583, consistent with fine-tuned code summarization benchmarks. Human evaluators rated accuracy and readability at 4.6/5.0, conciseness at 4.5/5.0, and completeness at 4.3/5.0. Mean generation time was 1.17 seconds per sample with a 100% success rate. CodeSage demonstrates that hybrid retrieval-augmented generation with domain-specific transformer models produces semantically accurate, readable documentation across multiple programming languages. It offers a practical productivity tool for Nigerian academic and professional software environments, with future work targeting domain-specific fine-tuning and expanded multilingual support.