Add Docs.hasdoc

[jariji]

Add @stevengj's Docs.hasdoc from #51174.

check_documented still should be added but that can happen separately.

[stevengj]

Needs a NEWS.md item.

Should also be mentioned in doc/src/manual/documentation.md.

[jariji]

I don't know why it's failing.

[stevengj]

The CI failures look like unrelated glitches in the test system.

[stevengj]

@vtjnash, @malmaud, is this good to merge?

[vtjnash]

Seems good to go

[LilithHafner]

Late to the party here, but wouldn't has_docstring be a more appropriate name as that is what this function actually checks? (a function may be documented via a mechanism other than a docstring)

Also this function should be public.

[jariji]

a function may be documented via a mechanism other than a docstring

You mean it might be in the manual somewhere? I don't think I'd call a function "documented" if it doesn't have a docstring. Maybe others disagree?

[LilithHafner]

I was thinking about the other direction as well. If a function has a docstring but is not in the manual then, in Julia base at least, it is not considered "documented". E.g. the 1.10 API is defined in part with

Functions, types, and constants are not part of the public API if they are not included in the documentation, even if they have docstrings.

[jariji]

I'd kinda forgotten about that policy. Tbh I don't see the advantage of it.

I would think if a function is public it should be considered part of the API. I tend to think the manual is secondary to the experience of living in the runtime and using ? --- if it points me to a manual page, I'll read it for context, but I don't think it's good to have to check an external manual to know whether a public function-with-docstring is "documented" or "public" so I can rely on it. I'd prefer a policy where I can check the API status of a function easily from within the system.

[DilumAluthge]

Late to the party here, but wouldn't has_docstring be a more appropriate name as that is what this function actually checks? (a function may be documented via a mechanism other than a docstring)

I also think that this should be named has_docstring, to reduce ambiguity.

[DilumAluthge]

Late to the party here, but wouldn't has_docstring be a more appropriate name as that is what this function actually checks? (a function may be documented via a mechanism other than a docstring)

#52724

[stevengj]

Late to the party here, but wouldn't has_docstring be a more appropriate name as that is what this function actually checks?

I disagree, for reasons stated in #52724 (comment) — this is in the Docs module, and in that context "doc" always refers to docstrings.