Creating In code Documentation

In this lesson we’ll show practical, repeatable techniques for writing documentation inside your codebase and using tools like GitHub Copilot to accelerate the process. The examples are built around a small FastAPI-based fake-data service (see Python API Development with FastAPI). Focus areas include concise docstrings, model documentation, example payloads, logging expectations, and README generation.

Automatically generated documentation is an excellent jumpstart, but always verify parameter names, types, and examples against the real code before committing changes.

Why in-code documentation matters:

Improves developer onboarding and reduces context switching.
Enables auto-generated API docs (OpenAPI/Swagger) and richer IDE hints.
Makes code reviews faster by clarifying intent and edge cases.

1) Quick inline comments and docstrings

Place comments and docstrings close to the code they describe. Use comments (#) for short clarifications and docstrings for function/class-level intent, parameters, and return shapes. Well-written docstrings help IDEs, linters, and documentation generators. Example router function with a clear docstring:

from fastapi import APIRouter
from api.models.fake_data_request import FakeDataRequest
from data.fake_data_repository import get_fake_data

router = APIRouter()

@router.post("/getfakedata")
async def generate_fake_data(request: FakeDataRequest) -> dict:
    """
    Generate fake data based on the provided request parameters.

    Args:
        request (FakeDataRequest): Request model containing:
            - `count` (int): Number of items to generate.
            - `locale` (str, optional): Locale to use for generation (default: "en_US").

    Returns:
        dict: JSON response containing:
            - `data` (list): Generated fake data items.

    Example:
        Request: POST /getfakedata
        {
            "count": 5,
            "locale": "en_US"
        }
        Response:
        {
            "data": [...generated items...]
        }
    """
    # Retrieve fake data using the repository function
    data = get_fake_data(request.count, request.locale)
    # Return data wrapped in a dictionary for a JSON response
    return {"data": data}

Best practices for docstrings:

Match parameter names and types exactly to the function signature and models.
Keep docstrings short and focused on intent, edge cases, and required fields.
Include at least one minimal example for request/response when it aids understanding.

2) Model docstrings

Document Pydantic models so field purpose and constraints are clear; this improves validation and generated API docs. Example Pydantic model with a concise docstring:

from pydantic import BaseModel
from typing import Optional

class FakeDataRequest(BaseModel):
    """
    Request model for fake data generation.

    Attributes:
        count (int): Number of records to generate.
        locale (str, optional): Locale for data generation (default: "en_US").
    """
    count: int
    locale: Optional[str] = "en_US"

Tip: If a field has constraints (min/max, pattern), include that in the docstring or use Pydantic field validators and include descriptions so OpenAPI reflects them.

3) Using Copilot / AI to generate comments

Copilot and similar AI tools are helpful for bootstrapping docstrings and inline comments. Use focused prompts and always review outputs for correctness. Suggested prompts:

“Add clear docstrings and example request/response for this FastAPI endpoint.”
“Explain why this function implements the current algorithm and any edge cases.”

Example refined output (after editing):

# Initialize FastAPI router instance
router = APIRouter()

@router.post("/getfakedata")
async def generate_fake_data(request: FakeDataRequest) -> dict:
    """
    Generate fake data based on the provided request parameters.

    Args:
        request (FakeDataRequest): Request model containing count and optional locale.

    Returns:
        dict: JSON response with key 'data' containing the generated items.
    """
    data = get_fake_data(request.count, request.locale)
    return {"data": data}

Copilot tips:

Run a suggestion, then inspect for incorrect field names (e.g., it may suggest data_type when your model uses count).
Use the AI output as a draft—correct types, defaults, and descriptions before committing.
For README generation, prompt for specific sections (Installation, Usage, Environment variables) rather than an entire generic file.

4) Representative server logs

When running the FastAPI app with Uvicorn, these are typical logs for startup and a successful POST:

INFO:     Started server process [25076]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     127.0.0.1:56608 - "POST /getfakedata HTTP/1.1" 200 OK

Example validation error when payload is missing or invalid:

INFO:     127.0.0.1:56599 - "POST /getfakedata HTTP/1.1" 422 Unprocessable Entity

Use logs to:

Confirm endpoint reachability and response codes.
Debug validation errors and missing required fields.
Trace request sources and latency in development environments.

5) Generating README and repository docs

Copilot can generate README skeletons and initial documentation pages. Prefer targeted prompts and iterate on generated content to ensure accuracy. Concise README example structure you can prompt for:

Project title and short description
Features
Requirements
Installation
Usage
Environment variables / config
Contributing and testing

Example generated README fragment:

A FastAPI-based service that generates realistic fake data for development and testing.

## Features

- Generate fake personal data (names, emails, ages, cities, occupations)
- REST API endpoints for programmatic access
- PEP8-compliant Python codebase

## Requirements

- Python 3.8+
- Dependencies listed in `requirements.txt`

## Installation

```sh
git clone https://github.com/yourusername/fake-data-generator.git
cd fake-data-generator
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```text

## Usage

```sh
uvicorn main:app --reload
```I don't see any text to examine — please paste the code, console output, or plain text you want classified.

Caveats:

Generated READMEs may omit critical steps (database setup, environment variables). Always add project-specific instructions.
Break README generation into smaller prompts (e.g., “Write Usage section for this FastAPI app”) if the first output is incomplete.

6) When to comment and what to avoid

Comment to explain “why” (design decisions, non-obvious trade-offs), not “what” the code does.
Prefer self-documenting code: meaningful variable/function names plus concise docstrings.
Keep documentation synchronized with code changes; outdated docs are worse than none.
Use example request/response shapes in docstrings when they speed up understanding.

Practical checklist:

Item	Purpose	Example
Function docstring	Explain purpose, inputs, outputs	`generate_fake_data` docstring above
Model docstring	Clarify fields and defaults	`FakeDataRequest` model
Inline comment	Short clarifier for tricky logic	`# Remove duplicates while preserving order`
README Usage	How to run and test the app	`uvicorn main:app --reload`
Logs	What to expect during startup and requests	See representative server logs above

AI-generated documentation can include incorrect assumptions. Always verify parameter names, types, and endpoints against your actual code before committing generated docs.

Links and References

Python API Development with FastAPI
GitHub Copilot in Action
FastAPI docs: https://fastapi.tiangolo.com/
Pydantic docs: https://pydantic-docs.helpmanual.io/

Conclusion

Use automated tools like Copilot to bootstrap docstrings, examples, and READMEs, but treat the output as a draft. Combine AI-generated content with focused edits to ensure accuracy, up-to-date examples, and clear intent. That process helps make your codebase more accessible, maintainable, and easier for team members to adopt.

Introduction

GitHub Copilot Basics

Prompt Engineering with Copilot

Advanced Features

Management of GitHub Copilot

Using Copilot Efficiently

Creating In code Documentation

1) Quick inline comments and docstrings

2) Model docstrings

3) Using Copilot / AI to generate comments

4) Representative server logs

5) Generating README and repository docs

6) When to comment and what to avoid

Links and References

Conclusion

Watch Video

​1) Quick inline comments and docstrings

​2) Model docstrings

​3) Using Copilot / AI to generate comments

​4) Representative server logs

​5) Generating README and repository docs

​6) When to comment and what to avoid

​Links and References

​Conclusion

Watch Video

1) Quick inline comments and docstrings

2) Model docstrings

3) Using Copilot / AI to generate comments

4) Representative server logs

5) Generating README and repository docs

6) When to comment and what to avoid

Links and References

Conclusion