Skip to content
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

Open
unforced opened this issue Sep 30, 2021 · 4 comments
Open

Top level docs are mis-placed or missing in most files #6776

unforced opened this issue Sep 30, 2021 · 4 comments
Labels
priority: p3 Desirable enhancement or fix. May not be included in next release. samples Issues that are directly related to samples. type: cleanup An internal cleanup or hygiene concern.

Comments

@unforced
Copy link
Contributor

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.

@product-auto-label product-auto-label bot added the samples Issues that are directly related to samples. label Sep 30, 2021
@danoscarmike danoscarmike added the type: docs Improvement to the documentation for an API. label Oct 1, 2021
@dandhlee dandhlee added the priority: p2 Moderately-important priority. Fix may not be included in next release. label Feb 19, 2022
@dandhlee dandhlee assigned dandhlee and unassigned nicain Feb 19, 2022
@dandhlee
Copy link
Collaborator

Only 1331 region tags to check 🤩

@dandhlee
Copy link
Collaborator

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.

@yoshi-automation yoshi-automation added the 🚨 This issue needs some love. label Mar 29, 2022
@busunkim96 busunkim96 removed priority: p2 Moderately-important priority. Fix may not be included in next release. 🚨 This issue needs some love. labels Apr 1, 2022
@dandhlee dandhlee added the status: blocked Resolving the issue is dependent on other work. label Jun 19, 2022
@dandhlee
Copy link
Collaborator

We're investigating further with the style changes. I'll report back once the samples steering committee discusses this.

@kweinmeister kweinmeister added the priority: p2 Moderately-important priority. Fix may not be included in next release. label Jan 13, 2023
@dandhlee dandhlee added type: cleanup An internal cleanup or hygiene concern. priority: p3 Desirable enhancement or fix. May not be included in next release. and removed status: blocked Resolving the issue is dependent on other work. type: docs Improvement to the documentation for an API. priority: p2 Moderately-important priority. Fix may not be included in next release. labels Jan 18, 2023
@dandhlee
Copy link
Collaborator

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.

@dandhlee dandhlee removed their assignment Jan 18, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
priority: p3 Desirable enhancement or fix. May not be included in next release. samples Issues that are directly related to samples. type: cleanup An internal cleanup or hygiene concern.
Projects
None yet
Development

No branches or pull requests

7 participants