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

Rename Docs.hasdoc to Docs.hasdocstring, to reduce ambiguity #52724

Closed
wants to merge 1 commit into from

Conversation

DilumAluthge
Copy link
Member

@DilumAluthge DilumAluthge commented Jan 3, 2024

Docs.hasdoc was introduced in #52139 (4209474), which hasn't made it into a release branch yet.

The term "documented" can have multiple meanings:

  1. "X is documented" can mean "X is listed in the manual".
  2. "X is documented" can mean "X has a docstring".

Therefore, I think the name Docs.hasdoc is a little confusing/ambiguous. I think it would be better to rename the function to Docs.hasdocstring (or Docs.has_docstring), to make it more clear what this function is doing.

Some more discussion in #52139 (comment) and #52139 (comment).

@DilumAluthge DilumAluthge requested a review from stevengj January 3, 2024 23:41
@DilumAluthge DilumAluthge mentioned this pull request Jan 3, 2024
@jariji
Copy link
Contributor

jariji commented Jan 3, 2024

That's fine with me.

@stevengj
Copy link
Member

stevengj commented Jan 4, 2024

I'm not sure I agree.

In the context of the Docs module, "doc" refers exclusively to docstrings. e.g. @doc, doc(...), etcetera. hasdoc is consistent with this. (The manual is a Documenter.jl concept.)

@LilithHafner
Copy link
Member

Triage agrees with @stevengj. Given that we use the term "doc" to refer to docstrings throughout the API, the right name for this is hasdoc.

@DilumAluthge DilumAluthge deleted the dpa/hasdocstring branch January 4, 2024 03:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants