| 1 |
> |
| 2 |
> I generally agree that comments are more visible/noticeable than |
| 3 |
> metadata, however, I also think that this could be a good step forward |
| 4 |
> for overall maintainability. The issue with documenting these things |
| 5 |
> in comments is that the comment lives only within the specific version |
| 6 |
> of the ebuild in which it is authored: it is up to the maintainer to |
| 7 |
> carry those comments over when version bumping. While this is |
| 8 |
> generally not a problem due to copy/paste, I think it is messy - there |
| 9 |
> could be an update to the comment from one version to the next, |
| 10 |
> meaning I now have two version of the comment floating around. |
| 11 |
> |
| 12 |
> With <note/>, there is one localized "source of truth" for this |
| 13 |
> documentation, which should remove any ambiguity. |
| 14 |
> |
| 15 |
> I would hope that after launching the <note/> feature, there would be |
| 16 |
> a gradual (or sudden?!) shift away from the current comments towards |
| 17 |
> the <note/> tag, maybe even including this in the dev manual. |
| 18 |
> |
| 19 |
|
| 20 |
That makes no sense, since the notes could be version-dependent. |
| 21 |
|
| 22 |
-- |
| 23 |
Andreas K. Hüttel |
| 24 |
dilfridge@g.o |
| 25 |
Gentoo Linux developer |
| 26 |
(council, toolchain, base-system, perl, libreoffice) |
Archives