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

[Junio C Hamano <gitster@pobox.com>]

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.

> 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.