On Mon, Jan 6, 2014 at 8:13 AM, Adam Williamson <awilliam@xxxxxxxxxx> wrote:
> On Mon, 2014-01-06 at 08:01 +0100, Lars E. Pettersson wrote:
>> On 01/06/2014 12:46 AM, Adam Williamson wrote:
>> > If it exists for backward compatibility, it doesn't necessarily need to
>> > be documented.
>>
>> Ehh? Why? Could you elaborate?
>
> I don't see what needs elaborating. I'm not aware that the 11th
> commandment is "Every Subcommand Must Be Documented, Even Ones You Just
> Put In So People Still Using Syntax From The Old Tool You're Replacing
> Won't Have A Problem". If that's the only reason a synonym of a
> documented subcommand exists, what's the point of documenting it? Anyone
> who needs it doesn't need documentation to find it - that's the *point*,
> if they were going to read the documentation, they'd know the *new*
> subcommand - and anyone who reads the documentation doesn't stand to
> gain anything from learning that a subcommand has a synonym for
> backwards compatibility purposes. So, why go to the trouble?
To make sure the inevitable next generation of contributors (or
authors of a rewrite) know not to throw the feature away, or design a
new system in a way that makes the feature impossible. It doesn't
necessarily need to be very emphasized, but it should be appropriately
documented.
Mirek
--
devel mailing list
devel@xxxxxxxxxxxxxxxxxxxxxxx
https://admin.fedoraproject.org/mailman/listinfo/devel
Fedora Code of Conduct: http://fedoraproject.org/code-of-conduct
