On Mon, Mar 17, 2025 at 09:50:53PM +0100, Jakub Jelinek wrote:
> https://www.gnu.org/prep/standards/html_node/Change-Logs.html
> contains some of the reasons and something about the formatting etc.
> When you repeat the same description over and over, normally one just writes
> * cdf.y: Modify #includes that reference libgcobol.
> * cobol1.cc: Likewise.
> * except.cc: Likewise.
> etc. (or Ditto. instead of Likewise.).
> The filenames can have different length and in most cases (the above case
> is kind of special since it is a global modification of the files, not a
> change in a particular function) there is also often large function name,
> so if you tried to align the descriptions and still had to fit on 80
> columns, it really wouldn't fit or you could have there just one or two
> short words. Often the description doesn't fit on
> the same line fully and needs to be wrapped, the space in there is precious
> and consistency is more important than some beatiful look, especially when
> different people would have different opinions on what is nice.
>
> There is another rule, if the description contains multiple sentences,
> dot is followed by 2 spaces unless it is at the end of line (but that is a
> general formatting rule also e.g. in code comments).
Consider e.g. the following libstdc++-v3/ChangeLog entry:
PR libstdc++/115215
PR libstdc++/115218
* include/std/ranges
(concat_view::iterator::_S_invoke_with_runtime_index): Use
__builtin_unreachable in recursive lambda to certify it always
exits via 'return'.
(concat_view::iterator::iterator): In the const-converting
constructor, direct initialize _M_it.
(views::_Concat::operator()): Adjust constraints in the
single-argument case as per LWG 4082.
* testsuite/std/ranges/concat/1.cc (test01): Call it at runtime
too.
(test04): New test.
Aligning in that case would be terrible, the length of
(concat_view::iterator::_S_invoke_with_runtime_index)
and
(views::_Concat::operator())
are significantly different. In fact the first one is so large
that it can't be on the same line with the filename.
I'll also note that when code in the FE or library doesn't use
function overloading or namespaces or too many methods as opposed to
just normal functions, one can just use the name of the function
and e.g. doesn't need to supply the argument types, because it
isn't ambiguous.
As mentioned in the above documentation, the function names or
filenames shouldn't be truncated or wildcards used in them because
people actively search the ChangeLog for filenames and function names.
Jakub
