-
Notifications
You must be signed in to change notification settings - Fork 6.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Top level docs are mis-placed or missing in most files #6776
Comments
Only 1331 region tags to check 🤩 |
Filed b/221461626. We can use the fixit week to poke at the snippet files that don't conform to the style, but until then it won't be an easy task to try and get this in line. It is also going to be hard to enforce this for new snippets, which the FR will help. |
We're investigating further with the style changes. I'll report back once the samples steering committee discusses this. |
Closing the loop: after discussing with the steering committee, it was decided that the wording shouldn't mean that we must have top level comments, but rather encouraged and shouldn't be a restriction. However, this is still a good pattern to follow and it might be worth looking into this as a group at some point. It is a lot of work, so we'll likely have to use a fix-it week or something to go through a lot of the files. Marking it as a cleanup and p3 for now, to look back later. |
Per go/code-snippets-style#descriptive-top-level-comment, we should have top level comments that are placed outside of the region tags, to describe the snippets.
From a brief walk through some parts of the repo, I'm noticing most files don't have the top level comment at all, and I also a noticed a number of them, particularly in
storage/transfer_service
where they are wrongly placed inside the bounds of the region tag, causing them to render in the c.g.c docs, which doesn't seem is the desirable functionality.The text was updated successfully, but these errors were encountered: