Update for Documenter.jl v1

[hyrodium]

No description provided.

[devmotion]

The doc build fails currently because docs/Project.toml is missing a compat entry for Documenter. Could you add one to avoid that a future breaking update of Documenter breaks the docs again?

[devmotion]

The docstring for can_dual is not useful at all, and both functions are not exported. IMO including them in the docs should be discussed and proposed in separate issues (#682) and PRs, but not be part of upgrading to Documenter v1.

[hyrodium]

Documenter.jl v1 has warnonly=false keyword argument in makedocs. (JuliaDocs/Documenter.jl#2194), so makedocs will fail without adding the docs or setting warnonly=true.

These functions are already documented as docstrings, and I thought it would be okay to add them to the documentation. I understand these functions are not stable.
Should I replace "Other API" with "Internal API"?

[devmotion]

AFAIK you can set checkdocs = :exports.

[hyrodium]

Yeah, that's right.
My point is, that the ignored docstrings may confuse other users. The functions are documented as docstrings, so someone may think these functions are stable. I thought emphasizing that these functions are not stable would help that kind of people.

[devmotion]

But they are not exported, are they?

[devmotion]

To clarify, I think these functions should not be included in the documentation for the time being and only added if they are considered important enough and their docstrings are more useful.

[hyrodium]

Sorry, I don't quite understand.

Documentation should be written for both package users and developers, and including Internal API documentation will be useful for future package developers. Of course, if these docstrings are incorrect or meaningless, they should be removed, but that is not the case.

There are more functions and types that need to be written (#682), but I believe this is simply a matter of insufficient documentation, and not a reason to eliminate existing documentation.

[hyrodium]

While I am not the maintainer of the repository, I am open to following your guidance as the maintainer. If you believe that removing these documents is the best course of action, I am willing to proceed with that.

[devmotion]

AFAICT neither users nor developers should have to deal with can_dual and ≺, so even though there is a docstring I don't think it should be included in the documentation (to me it seems these are just more detailed comments). value, Dual, etc. are more relevant IMO: #682 (but this should be discussed and addressed separately)

[hyrodium]

Okay, I'll update this PR to remove them from the documentation.

I will write down additional my concerns for future reference:

• If we use checkdocs=:exports, that will be as harmful as warnonly=true because this package provides non-exported stable API.
• I agree that the docstrings are something like detailed comments. But it would be very hard to discuss whether new docstrings should be in the docs or not every time. The easiest way would be to document the all docstrings.

[hyrodium]

The doc build fails currently because docs/Project.toml is missing a compat entry for Documenter.

The doc build is not failing, but I agree with adding [compat] for future breaking changes in Documenter, and I have added the [compat].