Autodocumentation of core/orchestrator_core.go#2
Conversation
| // Bootstrap initializes the orchestrator. | ||
| // It returns an error if the orchestrator is already bootstrapped. | ||
| // Returns: | ||
| // - utils.BootstrapError if the orchestrator is already bootstrapped |
There was a problem hiding this comment.
I'm leery of these specific errors being described here. The meaning of BootstrapError is wrong, and the other two don't exist.
|
|
||
| // Updates the o.volumes cache with the latest backend data. This function should only edit o.volumes in place to avoid | ||
| // briefly losing track of volumes that do exist. | ||
| // bootstrapVolumes adds existing volumes to the orchestrator |
There was a problem hiding this comment.
The generator ignored the non-conforming comment here. A better approach might be to preserve the human-created content, not add the generated description, but add the other sections.
There was a problem hiding this comment.
Would the existing comments have been recognized as function documentation and formatted as such by godoc? In my code I assumed that if the comment block didn't start with "// function_name" then it was just comments rather than actual doc. I can change that and assume the opposite (and expand with parameters, returns, example)
| // Parameters: | ||
| // ctx - context for the operation | ||
| // Returns: | ||
| // error - any error encountered |
There was a problem hiding this comment.
"any error encountered" ... kinda obvious!
| return o.cloneVolumeInitial(ctx, volumeConfig) | ||
| } | ||
|
|
||
| // cloneVolumeInitial creates a new volume by cloning an existing volume. |
There was a problem hiding this comment.
The AI fails to distinguish the separate roles of cloneVolumeInitial() and cloneVolumeRetry, which are similar to the human-commented addVolumeInitial() and addVolumeRetry(). Deeper insight is needed to get these right, and this is a case where I would overwrite the AI content to add more color.
| } | ||
| } | ||
|
|
||
| // GetVolumeTransaction returns a volume transaction from the backend |
There was a problem hiding this comment.
This is simply wrong. The transaction records are kept in the persistent store, not the backends. In fact, the code here and in the called method contains no mention of a backend, so the AI is really off in the weeds here.
| return snapshots, nil | ||
| } | ||
|
|
||
| // ReadSnapshotsForVolume returns a list of snapshots for the specified volume |
There was a problem hiding this comment.
Here is another case where deeper insight would help. The previous method ListSnapshotsForVolume() returns all snapshots cached here in the orchestrator core, while ReadSnapshotsForVolume() invokes storage APIs to get the list of snapshots directly from a storage backend. The comment here isn't wrong, but it could be much more helpful.
| // Parameters: | ||
| // backendUUID - backend to check | ||
| // Returns: | ||
| // (capable, error) |
There was a problem hiding this comment.
Odd that it has 2 on one line with no documentation.
There was a problem hiding this comment.
That I think I can address in my script. I am going to verify that openAi generates the expected number of lines under "// Returns"
| return nil | ||
| } | ||
|
|
||
| // updateVolumeOnPersistentStore updates the volume information in persistent store |
There was a problem hiding this comment.
There's some inconsistency in how it generates this. Sometimes it generates "in the persistent store" and sometimes it leaves off the article "the" and just generates "persistent store".
| // Parameters: | ||
| // nodeName: name of the node to get the list of VolumePublications for | ||
| // Returns: | ||
| // []*utils.VolumePublication: list of VolumePublications for the given node |
There was a problem hiding this comment.
Seems to have gotten confused and listed the type of the return []*utils.VolumePublication, rather than the name publications
There was a problem hiding this comment.
Is it possible here that the name is less interesting than the type for the user? The model returned the type quite a few times in autogenerated docs elsewhere in this file.
There was a problem hiding this comment.
Whichever, as long as it's consistent
| // recordTiming is used to record in Prometheus the total time taken for an operation as follows: | ||
| // defer recordTiming("backend_add")() | ||
| // see also: https://play.golang.org/p/6xRXlhFdqBd | ||
| // It returns an error if the backend update is invalid. |
There was a problem hiding this comment.
I like that the script can enhance an existing comment. How does that work with subsequent comment regeneration? Can the script still distinguish between manual and autogenerated content?
There was a problem hiding this comment.
Currently the whole doc for that function would be detected as "fair play" and possibly rewritten when the hash changes.
There was a problem hiding this comment.
Does that mean a regeneration would overwrite the original manually-generated content? That would seem problematic. I wondered if your It returns language was a cue that anything before that was to be preserved, but I see that is frequently used by the AI. What else might work?
There was a problem hiding this comment.
It might overwrite the original manual content yes. But possibly that content became obsolete with the code change yes? The human writing the new code would decide whether the generated doc is acceptable. If it isn't they would updated it manually and remove the autogenerated tag?
There was a problem hiding this comment.
The hash line starts with // --. If the script placed another delimiter line between preexisting & generated content, it could preserve the former during an update. Thoughts, @ntap-rippy?
| return nil | ||
| } | ||
|
|
||
| // deleteNode deletes a node from the backend. |
There was a problem hiding this comment.
This is a bit misleading. As with the previous function, this one deletes a node from Trident, and it removes access to that node from all backends. We may have to push a commit atop the AI generated content to fix those things it doesn't quite grok.
3 participants
Change description
Smaller PR for autodocumentation