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

Doc: remove redundant refs in sqlite3 docs #94667

Closed

Conversation

erlend-aasland
Copy link
Contributor

@erlend-aasland erlend-aasland commented Jul 7, 2022

Each type can be ref'ed using the :class: directive; there is no reason to provide duplicate :ref:'s.

@erlend-aasland
Copy link
Contributor Author

See #94620 (comment)

@erlend-aasland
Copy link
Contributor Author

FTR, I checked that there is no existing ref's to these in other parts of the docs (NEWS items, What's New, etc.)

Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to note, perhaps a little pedantic but the ref targets aren't completely syntactically and semantically redundant—their targets are the sections, while the :class: directive target is the class item, which can make both a syntactic and semantic difference in some contexts. If content outside the class directive, such as an introduction, examples, or other classes/objects is added to the section, then the class directive is not practically equivalent, especially so in practice if the content is added above the linked class, or in a different scope.

In this case, the only current examples of this are a versionadded directive above the Blob class, and some rather lengthy examples below the Row class (which besides being a little lengthy for the context, are somewhat confusing, since it references "the example given above", but is unclear which of the many examples this is—evidently the one in the document introduction). However, additional such material could be added at any point in the future, in which case the refs should presumably be re-added.

Whether they are worthwhile to keep, though, is up to you.

Some other more minor notes:

  • If the class is ever renamed/replaced by another in the same section, class refs will break, wheres section refs will not. That's pretty unlikely, though.
  • While no internal links may be using it, it is theoretically possible that external links might, if there was a previous :ref: and they copied the link from that ref, (or manually did so, for a more robust link than relying on the section name not to change). But again, that's pretty unlikely.

@erlend-aasland
Copy link
Contributor Author

Nah, there's more important stuff to do with the sqlite3 docs than something like this. Churn for little value. I'm closing the PR. Thanks!

@erlend-aasland erlend-aasland deleted the sqlite-remove-unneeded-refs branch July 7, 2022 23:10
@CAM-Gerlach
Copy link
Member

Probably spent too much time writing that comment too myself 😅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants