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.

Sign up for GitHub

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

Jump to bottom

context: clarify documentation for TODO #56625

Open
adamkvitek opened this issue Nov 7, 2022 · 3 comments
Open

context: clarify documentation for TODO #56625

adamkvitek opened this issue Nov 7, 2022 · 3 comments
Labels
Documentation Issues describing a change to documentation. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Unplanned

Comments

@adamkvitek
Copy link

adamkvitek commented Nov 7, 2022 •
edited
Loading

The https://pkg.go.dev/golang.org/x/net/context?utm_source=godoc#TODO function description does not make it very clear that TODO is not a mistake (unfinished documentation), but an intentional name of the function. This was previously discussed in: #12591

Suggestions for improvement:

  • Formatting is not clear - context.TODO looks like there is a missing space after the sentence. Mark it as <code>context.TODO</code> to signify that this is a code.
  • Include a sentence to show that TODO is intentional (not unfinished documentation), for example: The name of this function is literally called TODO, this is not an unfinished documentation.
@gopherbot gopherbot added this to the Proposal milestone Nov 7, 2022
@adamkvitek adamkvitek changed the title proposal: affected/package: proposal: Make it obvious that TODO function is intentional Nov 7, 2022
@seankhliao seankhliao changed the title proposal: Make it obvious that TODO function is intentional context: clarify documentation for TODO Nov 7, 2022
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Nov 7, 2022
@seankhliao seankhliao added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. and removed Proposal labels Nov 7, 2022
@seankhliao seankhliao removed this from the Proposal milestone Nov 7, 2022
@seankhliao
Copy link
Member

  1. it should probably use the new link syntax: https://go.dev/doc/comment#links
  2. This doesn't seem necessary. The documentation for TODO should be clear enough that it makes sense.

@ianlancetaylor
Copy link
Member

CC @Sajmani

@seankhliao seankhliao added this to the Unplanned milestone Nov 19, 2022
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/501115 mentions this issue: context: add godoc links

gopherbot pushed a commit that referenced this issue Jun 6, 2023
@dolmen @gopherbot
context: add godoc links
1c89de6 
This clarifies the ambiguity of the TODO word as raised in
#56625.
Also links the introduction text to each function.

Note: linking from Context methods documentation is blocked for now by
#59728.

Change-Id: Ie6080bd8dee3a652436b0875ddc5f452287c9493
Reviewed-on: https://go-review.googlesource.com/c/go/+/501115
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: David Chase <drchase@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Run-TryBot: Ian Lance Taylor <iant@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
4 participants
@ianlancetaylor @gopherbot @seankhliao @adamkvitek