Back to all reviewers

Document API stability

tensorflow/swift
Based on 3 comments
Other

When working with AI frameworks and machine learning libraries, clearly document the stability state of APIs being used. For experimental or evolving features:

AI Other

Reviewer Prompt

When working with AI frameworks and machine learning libraries, clearly document the stability state of APIs being used. For experimental or evolving features:

  1. Add explicit warnings about API stability in documentation
  2. Provide workarounds for unstable features while indicating when they might be resolved
  3. Link to official documentation rather than source code when possible

For example, when documenting a feature with known limitations:

// EXPERIMENTAL: Boolean operators (&&, ||) are not differentiable in v0.11
// Use these alternative functions until the next release:
extension Bool {
    public static func and(_ a: Bool, _ b: Bool) -> Bool {
        if a {
            if b {
                return true
            }
        }
        return false
    }
    
    // Usage: if Bool.and(condition1, condition2) instead of if condition1 && condition2
}

// TODO: Remove when upgrading to Swift release with apple/swift/pull/33511

This approach helps users understand current limitations, provides immediate solutions, and establishes clear upgrade paths when the framework evolves.

3
Comments Analyzed
Other
Primary Language
AI
Category

Source Discussions