{"action":"created","issue":{"url":"https://api.github.com/repos/Nemocas/AbstractAlgebra.jl/issues/535","repository_url":"https://api.github.com/repos/Nemocas/AbstractAlgebra.jl","labels_url":"https://api.github.com/repos/Nemocas/AbstractAlgebra.jl/issues/535/labels{/name}","comments_url":"https://api.github.com/repos/Nemocas/AbstractAlgebra.jl/issues/535/comments","events_url":"https://api.github.com/repos/Nemocas/AbstractAlgebra.jl/issues/535/events","html_url":"https://github.com/Nemocas/AbstractAlgebra.jl/issues/535","id":527148497,"node_id":"MDU6SXNzdWU1MjcxNDg0OTc=","number":535,"title":"docstrings should not be added for every method of a function","user":{"login":"rfourquet","id":8462914,"node_id":"MDQ6VXNlcjg0NjI5MTQ=","avatar_url":"https://avatars1.githubusercontent.com/u/8462914?v=4","gravatar_id":"","url":"https://api.github.com/users/rfourquet","html_url":"https://github.com/rfourquet","followers_url":"https://api.github.com/users/rfourquet/followers","following_url":"https://api.github.com/users/rfourquet/following{/other_user}","gists_url":"https://api.github.com/users/rfourquet/gists{/gist_id}","starred_url":"https://api.github.com/users/rfourquet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rfourquet/subscriptions","organizations_url":"https://api.github.com/users/rfourquet/orgs","repos_url":"https://api.github.com/users/rfourquet/repos","events_url":"https://api.github.com/users/rfourquet/events{/privacy}","received_events_url":"https://api.github.com/users/rfourquet/received_events","type":"User","site_admin":false},"labels":[{"id":1689762023,"node_id":"MDU6TGFiZWwxNjg5NzYyMDIz","url":"https://api.github.com/repos/Nemocas/AbstractAlgebra.jl/labels/doc","name":"doc","color":"02d7e1","default":false,"description":"This change adds or pertains to documentation"}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":7,"created_at":"2019-11-22T11:42:32Z","updated_at":"2019-11-22T12:40:02Z","closed_at":null,"author_association":"COLLABORATOR","body":"The other day I wanted to know what `divexact` means, so I went in help mode:\r\n```julia\r\nhelp> divexact(10, 3)\r\n  divexact(a::AbstractAlgebra.ResElem{T}, b::AbstractAlgebra.ResElem{T}) where {T <: RingElement}\r\n\r\n  │  Return a/b where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(a::AbstractAlgebra.ResFieldElem{T}, b::AbstractAlgebra.ResFieldElem{T}) where {T <: RingElement}\r\n\r\n  │  Return a/b where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(f::AbstractAlgebra.PolyElem{T}, g::AbstractAlgebra.PolyElem{T}) where {T <: RingElement}\r\n\r\n  │  Return f/g where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(a::AbstractAlgebra.PolyElem{T}, b::T) where {T <: RingElem}\r\n\r\n  │  Return a/b where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(a::AbstractAlgebra.PolyElem, b::Union{Integer, Rational, AbstractFloat})\r\n\r\n  │  Return a/b where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::AbstractAlgebra.RelSeriesElem{T}, y::AbstractAlgebra.RelSeriesElem{T}) where {T <: RingElement}\r\n\r\n  │  Return x/y.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::AbstractAlgebra.RelSeriesElem, y::Union{Integer, Rational, AbstractFloat})\r\n\r\n  │  Return x/y where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::AbstractAlgebra.RelSeriesElem{T}, y::T) where {T <: RingElem}\r\n\r\n  │  Return x/y where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::AbstractAlgebra.AbsSeriesElem{T}, y::AbstractAlgebra.AbsSeriesElem{T}) where {T <: RingElement}\r\n\r\n  │  Return x/y.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::AbstractAlgebra.AbsSeriesElem, y::Union{Integer, Rational, AbstractFloat})\r\n\r\n  │  Return x/y where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::AbstractAlgebra.AbsSeriesElem{T}, y::T) where {T <: RingElem}\r\n\r\n  │  Return x/y where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::Generic.LaurentSeriesElem{T}, y::Generic.LaurentSeriesElem{T}) where {T <: RingElement}\r\n\r\n  │  Return x/y.\r\n\r\n  ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────[25/8474]\r\n\r\n  divexact(x::Generic.LaurentSeriesElem, y::Union{Integer, Rational, AbstractFloat})\r\n\r\n  │  Return x/y where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::Generic.LaurentSeriesElem{T}, y::T) where {T <: RingElem}\r\n\r\n  │  Return x/y where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::Generic.PuiseuxSeriesElem, y::Union{Integer, Rational, AbstractFloat})\r\n\r\n  │  Return a/b where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::Generic.PuiseuxSeriesElem{T}, y::T) where {T <: RingElem}\r\n\r\n  │  Return a/b where the quotient is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::Generic.MatrixElem, y::Union{Integer, Rational, AbstractFloat})\r\n\r\n  │  Return x/y, i.e. the matrix where each of the entries has been divided by y. Each division is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(x::Generic.MatrixElem{T}, y::T) where {T <: RingElem}\r\n\r\n  │  Return x/y, i.e. the matrix where each of the entries has been divided by y. Each division is expected to be exact.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(a::AbstractAlgebra.FracElem{T}, b::AbstractAlgebra.FracElem{T}) where {T <: RingElem}\r\n\r\n  │  Return a/b.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(a::AbstractAlgebra.FracElem, b::Union{Integer, Rational, AbstractFloat})\r\n\r\n  │  Return a/b.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(a::Union{Integer, Rational, AbstractFloat}, b::AbstractAlgebra.FracElem)\r\n\r\n  │  Return a/b.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(a::AbstractAlgebra.FracElem{T}, b::T) where {T <: RingElem}\r\n\r\n  │  Return a/b.\r\n\r\n  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\r\n\r\n  divexact(a::T, b::AbstractAlgebra.FracElem{T}) where {T <: RingElem}\r\n\r\n  │  Return a/b.\r\n```\r\nRIght, about 23 similar docstrings. With `Nemo` loaded, there will be about 32. \r\nOne problem is that as there is no specific docstring for `divexact(10, 3)`, the docstrings for all the methods are shown. Then I have to infer from unmatching docstrings what it would mean. At least, if there is a matching documented method, I get only one docstring instead of this wall of duplication. But if I ask for help on `divexact` (the function, not a method), I can't escape this tedious exercise of gazing at these specific docstrings to reconstruct the general meaning.\r\nAnother problem is that if there is a mistake in the docstring, it has to be fixed in all which contain the same mistake (usual problem with copy-pasting), cf. e.g.  https://github.com/Nemocas/Nemo.jl/pull/726.\r\n\r\nAlso, from Julia's [documentation](https://docs.julialang.org/en/v1.4-dev/manual/documentation/#Functions-and-Methods-1) on documentation:\r\n> Functions in Julia may have multiple implementations, known as methods. While it's good practice for generic functions to have a single purpose, Julia allows methods to be documented individually if necessary. In general, only the most generic method should be documented, or even the function itself (i.e. the object created without any methods by `function bar end`). Specific methods should only be documented if their behaviour differs from the more generic ones. In any case, they should not repeat the information provided elsewhere. For example:"},"comment":{"url":"https://api.github.com/repos/Nemocas/AbstractAlgebra.jl/issues/comments/557517015","html_url":"https://github.com/Nemocas/AbstractAlgebra.jl/issues/535#issuecomment-557517015","issue_url":"https://api.github.com/repos/Nemocas/AbstractAlgebra.jl/issues/535","id":557517015,"node_id":"MDEyOklzc3VlQ29tbWVudDU1NzUxNzAxNQ==","user":{"login":"wbhart","id":242598,"node_id":"MDQ6VXNlcjI0MjU5OA==","avatar_url":"https://avatars1.githubusercontent.com/u/242598?v=4","gravatar_id":"","url":"https://api.github.com/users/wbhart","html_url":"https://github.com/wbhart","followers_url":"https://api.github.com/users/wbhart/followers","following_url":"https://api.github.com/users/wbhart/following{/other_user}","gists_url":"https://api.github.com/users/wbhart/gists{/gist_id}","starred_url":"https://api.github.com/users/wbhart/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wbhart/subscriptions","organizations_url":"https://api.github.com/users/wbhart/orgs","repos_url":"https://api.github.com/users/wbhart/repos","events_url":"https://api.github.com/users/wbhart/events{/privacy}","received_events_url":"https://api.github.com/users/wbhart/received_events","type":"User","site_admin":false},"created_at":"2019-11-22T12:40:02Z","updated_at":"2019-11-22T12:40:02Z","author_association":"NONE","body":"How will you document in the online documentation, which types can be passed to a given function if you don't have docstrings for each. Generally there is more than one docstring because there is more than one section of the documentation that needs it.\r\n\r\nFor functions like divexact, which apply to all rings, it's not a problem. But this is a very small number of functions (they are described in the Ring interface in the AbstractAlgebra documentation). In general, in Nemo, functions are *only* documented if they provide functionality different from what is in the AbstractAlgebra documentation. In other words, we document that the given function is provided for that specific ring, even though it is not mandated for all rings.\r\n\r\nIt's not clear you are going to get far with this."}}
{"actor":{"display_login":"wbhart"}}