Re: [PATCH 05/10] evolve: add the change-table structure

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 28, 2022, 15:59 UTC
Message-ID: <xmqqh70rzdz9.fsf@gitster.g>
In-Reply-To: <72c4e8c9-62bb-96aa-7b42-d7103b7873eb@dunelm.org.uk>

Phillip Wood <phillip.wood123@gmail.com> writes:

> Chris if you want to use '/**' style comments for the API docs then
> please do so consistently and do not use them elsewhere.

Thanks.

Show 5 quoted lines

> I've come across them in projects that use gtk-doc or other
> documentation generators where it is necessary to distinguish
> 'documentation' from 'code comments'. I don't think they add much
> value if one is not generating documentation from the source, it is
> just one more thing for contributors to remember.

Yes, I personally find them annoying, but has tolerated them so far, hoping that something good (read: automated documentation out of comments) emerge someday, simply because the first ones were added by folks who were interested in that direction, which unfortunately has never materialized.

Maybe it would eventually happen, but I think there are a lot of clean-up to do before it happens. I somehow suspect that the sooner the mechanism to create the documentation set, however incomplete and messy the result is with the current material, the more incentive the contributors have to apply /** vs /* distinction properly, but of course on the other hand, until the existing material gets cleaned up, the care they need to take to make the distinction does feel like a makework. So, I dunno.

Thanks.