Follow commenting convention for copyright headers.

[jkoshy]

Use "/*-" for the first line of copyright header comments.

Doing so allows automation to collect license information in a source tree by looking for comments that start with "/*-".

This is a comment-only change that does not affect code behavior.

[Quuxplusone]

This seems reasonable enough, but the commit message should explain something about why we're doing this and why this (specifically) is the right thing to do. You say this "allows automation to ..."; but whose automation? is there a well-known standard for this? do any existing tools support special behavior for /*- comments?
A quick google for "copyright header comments" didn't turn up any mentions of /*-.

[jkoshy]

Thanks for the review. I have added more context to the commit message.

[Quuxplusone]

Thanks for the review. I have added more context to the commit message.

Thanks! The link to https://man.freebsd.org/cgi/man.cgi?query=style is indeed very useful. But I guess the next level of that rabbit hole is: should we also be using a SPDX-License-Identifier: line? https://spdx.dev/learn/handling-license-info/#where But then if we look at how other projects are using that, we see they're not using the /*- convention at all; e.g. https://lwn.net/Articles/739183/

So I feel like I still have basically the same question: This commit is certainly harmless/cosmetic, but who specifically will be helped by it? Is anyone willing to say "yes, this change will specifically make my workflow easier, in the following concrete way..."? Or to put it another way, suppose we did this, and then next year someone comes and asks for /*- to be replaced with /*** because their specific workflow benefits from /*** — should I say "okay, sure," or should I say "sorry, we can't do that because it would break ___'s workflow for creating the ____ package on ____ OS"? If the answer would be "okay, sure," then I shouldn't take this patch. Or, if not, then those blanks need filling in.

Btw, I have basically no idea how uthash is packaged into various package managers. A great way to sell this patch would be to show me some links to where one or more package maintainers maintain their own distribution-specific patchsets against uthash, and show that this patch brings uthash trunk closer-into-line with one or more distributions (allowing them to shrink their patchsets). Such a list of links would also be a great addition to the README!

[jkoshy]

Is anyone willing to say "yes, this change will specifically make my
workflow easier, in the following concrete way..."

The change would make my own workflow a tiny bit easier. For example, a change like [Elftoolchain:r4024] could become a copy instead of a copy-edit.

This convenience propagates downstream because uthash's source code is used by downstream projects via imports of Elftoolchain code—for example: FreeBSD, Minix, NetBSD, RTEMS.

Following the /*- convention upstream would make it easier for users of those open-source projects to locate and process the (c) blocks in their source base correctly.

who specifically will be helped by it?

1. Developers using uthash, either directly or indirectly (as above), who need to conduct due diligence around the licenses in their source trees.
2. People wishing to preserve pre-formatted content such as a (c) coment block when running formatters over their C/C++ code.

Or to put it another way, suppose we did this, and then
next year someone comes and asks for /- to be replaced
with /**

Although possible, this seems unlikely because tooling support for the alternate /*** marker would also need to be implemented.

BSD projects have used /*- to mark (c) comments for over three decades, as of the writing. *BSD tools that process source code (for example, BSD indent(1)) know about the /*- convention. Such tooling would need to be augmented to support the alternate /*** convention for marking (c) blocks, which is likely to involve a considerable amount of work.

should we also be using a SPDX-License-Identifier: line

The SPDX identifier has a different function than the /*- marker. IMHO it would be useful to add it.

Would you like me to revise the patch to add in the appropriate SPDX line?

[Quuxplusone]

People wishing to preserve pre-formatted content such as a (c) comment block when running formatters over their C/C++ code.

That's a good point. clang-format is smart enough to leave block comments alone, but as you (partly) pointed out, BSD indent is not. indent knows about "box comments" of the form [/][*][*-]+. But indent doesn't intrinsically treat /*- any differently from, well, /***! (Verified via my MacBook's /usr/bin/indent.)

The change would make my own workflow a tiny bit easier. For example, a change like [Elftoolchain:r4024] could become a copy instead of a copy-edit.

OTOH (moving the goalposts, I admit), that edit was needed only to preserve [r3983] (May 2022)'s addition of /*-.

The SPDX identifier has a different function than the /*- marker. IMHO it would be useful to add it.
Would you like me to revise the patch to add in the appropriate SPDX line?

I don't know! This highlights my basic concern here, that we're changing a (trivial) thing without a concrete notion that what we're changing it to is best, or even better. [r4024] didn't bother to add a SPDX line, despite the BSD "kernel source file style guide" mandating one; so why should we take the /*- mandate any more seriously than the SPDX mandate?

Another plausible option would be to remove the copyright headers from all uthash's files and rely on the existing LICENSE file to communicate that information. But that option, also, is not clearly better than the status quo and I'm not inclined to pursue it without a good reason.

The Minix repo you linked to uses plain /* in uthash.h (for at least the past 8 years), and I guess they've survived. libpng uses plain /*. zlib uses plain /*. libc++ uses plain // with SPDX-License-Identifier. glibc uses plain /*. PCRE2 uses plain /*. protobuf-c uses plain /*. librdkafka uses plain /*. xxHash uses plain /* (and uses /*-**** for a few non-(c) comments).

I see no consensus in favor of /*- here, and while maybe there needs to be a "first penguin," I don't see why it should be uthash specifically.