Skip to content

document internal/utils#211

Merged
gflarity merged 1 commit into
ai-dynamo:mainfrom
gflarity:gflarity/document_internal_utils
Oct 22, 2025
Merged

document internal/utils#211
gflarity merged 1 commit into
ai-dynamo:mainfrom
gflarity:gflarity/document_internal_utils

Conversation

@gflarity

@gflarity gflarity commented Oct 4, 2025

Copy link
Copy Markdown
Contributor

What type of PR is this?

documentation

What this PR does / why we need it:

Document internal/utils

Special notes for your reviewer:

Prompt:

Improve the inline documentation for for all golang files under this directory/package. Here are the rules to follow:

  • Use concise idiomatic go documentation principles.
  • Ensure correctness.
  • Add some minimal inline documentation above complex code blocks when to explain the intent of the code.
  • Don't document code that is clearly self documenting.
  • Blocks of code should only have a comment describing them if it is practical and valuable.
  • Don't change the code or variable names.
  • All functions to should have concise accurate documentation with the exception of command "main" functions which are obviously entry points.
  • Document field structs but don't duplicate the field documentation above.
  • Avoid duplicate documentation, just pick the most appropriate place.
  • Large or complex blocks of code that aren't self documenting should be documented.
  • Avoid re-writing any existing documentation unless it's incomplete, or incorrect

Example of documentation that isn't useful and should be avoided:

// It uses JSON format at INFO level for structured logging.
var (
log = logger.MustNewLogger(false, configv1alpha1.InfoLevel, configv1alpha1.LogFormatJSON).WithName("grove-initc")
)```. 

Examples of documentation that doesn't add value: 
```  // Parse the replica count as an integer
replicas, err := strconv.Atoi(nameAndMinAvailable[1])
if err != nil {
 return nil, groveerr.WrapError(err, errCodeInvalidInput, operationParseFlag, "failed to convert replicas to int")
}
  // Store the PodClique name and its minimum available replicas
  podCliqueDependencies[strings.TrimSpace(nameAndMinAvailable[0])] = replicas
// Initialize the configuration with empty PodClique list
 config := CLIOptions{
  podCliques: make([]string, 0),
 }
 // Register all command line flags
 config.RegisterFlags(pflag.CommandLine)
 // Parse the command line arguments
 pflag.Parse()
 // Get the in-cluster REST configuration
 restConfig, err := rest.InClusterConfig()
// Get the pod informer from the factory
typedInformer := factory.Core().V1().Pods().Informer()

Systematically check every golang file under this directory is documented as per the instructions above.

Does this PR introduce a API change?

None

Signed-off-by: Geoff Flarity <gflarity@nvidia.com>
@gflarity gflarity requested a review from unmarshall as a code owner October 4, 2025 03:28
@gflarity gflarity added the documentation Improvements or additions to documentation label Oct 4, 2025
@gflarity gflarity merged commit 90fc51d into ai-dynamo:main Oct 22, 2025
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants