Add comprehensive function documentation for get_instance_details()

[senomorf]

Documentation Enhancement: Function Documentation

Issue Description

The get_instance_details() function in scripts/notify.sh lacks comprehensive documentation, making it difficult for maintainers to understand its behavior, parameters, and error handling approach.

Current State

The function exists without proper documentation:

get_instance_details() {
    # No documentation currently exists
    local instance_id="$1"
    local shape_name="$2"
    # ... implementation continues
}

Impact on Maintainability

• Unclear parameter requirements and expected formats
• Undefined return behavior in success/failure scenarios
• Unknown error handling approach for API failures
• Missing context about when the function should be used
• No guidance on expected outputs or side effects

Recommended Documentation

Add comprehensive function documentation:

#################################################################
# Get detailed instance information for notifications
#
# Fetches comprehensive instance details from OCI API including
# OCID, IPs, availability domain, and connection information.
# Designed for notification system with graceful error handling.
#
# Args:
#   instance_id  - OCI instance OCID to fetch details for
#   shape_name   - Human-readable shape name for display 
#                 (e.g., "A1.Flex (ARM)", "E2.1.Micro (AMD)")
#
# Returns:
#   Formatted instance details string with:
#   - Instance ID (OCID)
#   - Public IP address (or "Not assigned" if none)
#   - Private IP address (or "Not available" if missing)
#   - Availability Domain (short format: "AD-1", "AD-2", etc.)
#   - Instance state (RUNNING, STOPPED, etc.)
#
# Error Handling:
#   - Continues workflow even if detail fetching fails
#   - Falls back to null IP values for VNIC failures  
#   - Returns basic notification if API calls fail
#   - Logs warnings for troubleshooting without breaking flow
#
# Side Effects:
#   - Makes multiple OCI API calls (instance get, VNIC list, VNIC get)
#   - Writes formatted output to stdout
#   - May log debug/warning messages
#
# Dependencies:
#   - Requires oci_cmd function for API access
#   - Needs jq for JSON parsing
#   - Uses log_error, log_warning functions for output
#
# Example Usage:
#   get_instance_details "ocid1.instance.oc1...." "A1.Flex (ARM)"
#
# Example Output:
#   **A1.Flex (ARM)** (VM.Standard.A1.Flex):
#   • ID: ocid1.instance.oc1.ap-singapore-1.aaa...
#   • Public IP: 123.456.789.0
#   • Private IP: 10.0.1.5
#   • AD: AD-1
#   • State: RUNNING
#
#################################################################
get_instance_details() {

Benefits

• Improved maintainability for future developers
• Clear parameter expectations preventing misuse
• Documented error handling for troubleshooting
• Usage examples for proper implementation
• Expected output format for integration testing

Priority

Low - Documentation improvement that supports long-term maintainability.

Context

Identified in PR #89 code review by Claude Code automated review system.

Acceptance Criteria

• Add comprehensive function header documentation
• Document all parameters with types and formats
• Explain return values and output formats
• Document error handling behavior
• Include usage examples
• Note dependencies and side effects
• Add example of expected output format