api docs: BGradient doc missing

[nephele]

This seems to already have doxygen files backing it, but they don't seem to correspond to any page for BGradient.

[madmax]

Replying to nephele:

This seems to already have doxygen files backing it, but they don't seem to correspond to any page for BGradient.

Those are marked as INTERNAL, so not generated by default. And then they are basically placeholders with "Undocumented", so despite having the files, they still have no content.

[nielx]

Generally, I mark any APIs as private when they are in the BPrivate namespace. For BGradient, this is not the case, but the ​comment at the top of the file seemed to indicate that this is internal.

There is no rule against documenting it, so feel free to provide patches. We can also discuss whether it should be stabilized, but that goes beyond this documentation ticket.

[pulkomandy]

If we document it, a warning should be added in the documentation that it is not part of the stable API. As with many of the "private" classes, this gets some use in 3rd party applications and it is difficult, or at least annoying, to write code that does not use it when you want a gradient.

Ideally the code would be shipped in a static library, but in the case of BGradient, the tight coupling with BView makes it difficult to do so. So indeed, people should be even more careful here than they should be with private classes that are in separate libraries.