Yes, documentation should be dry, in so far as things which are used and look identical except for trivial differences (types mostly, though they should still follow an obvious pattern, as the principle of least surprise demands) should be documented only once together.

And no, that the documentation is only written once is nearly completely interesting, if it has to be read multiple times. DRY applies to what the consumer interacts with too, not only with what the provider does to create it.

No in so far as there should be enough examples to demonstrate use of the API, and as a starting-point to doing things should be there, and those are obviously repeating the rest.

Also, higher-level overviews can be extremely useful in exploring what something is about, what it could be used for, why it is as it is, and thus understanding capabilities and limitations. They summarize and set the details into context, thus per se repeating information.

Unfortunately, doc-comments and similar systems while quite good for documenting each entity (type, member, whatever) in isolation is, are harder to use up to unusable for that.

At least merging the documentation of a group of entities defined together (same file, top of same scope) is not too hard to implement, even if each entity gets an additional notes-section. The first entity would add a new doc-comment like merge, while the others replace theirs. Merging those notes where appropriate under the same heading can get arbitrarily difficult though.

Linking to commonalities while far easier to implement, doesn't get rid of the repetition, and makes each part harder to read.

Yes, documentation should be dry, in so far as things which are used and look identical except for trivial differences (types mostly, though they should still follow an obvious pattern, as the principle of least surprise demands) should be documented only once together.

And no, that the documentation is only written once is nearly completely uninteresting, if it has to be read multiple times. DRY applies to what the consumer interacts with too, not only with what the provider does to create it.

No in so far as there should be enough examples to demonstrate use of the API, and as a starting-point to doing things, and those are obviously repeating information.

Also, higher-level overviews can be extremely useful in exploring what something is about, what it could be used for, why it is as it is, and thus understanding capabilities and limitations. They summarize and set the details into context, thus per se repeating information.

Unfortunately, doc-comments and similar systems while quite good for documenting each entity (type, member, whatever) in isolation, are much harder to pretty useless for that.

At least merging the documentation of a group of entities defined together (same file, top of same scope) is not too hard to implement, even if each entity gets an additional notes-section. The first entity would add a new doc-comment like merge, while the others replace theirs. Merging those notes where appropriate under the same heading can get arbitrarily difficult though.

Linking to commonalities while far easier to implement, doesn't get rid of the repetition, and makes each part harder to read.