Branko Čibej wrote:
> Well, now I'll review that commit. :-)
>
>> Add explanatory comments to some example files.
>>
>> * tools/xslt/svnindex.css
>> * tools/xslt/svnindex.xsl
>> Add comments that say what these files are.
>>
> Log format's wrong; should be:
>
> * tools/xslt/svnindex.css,
> tools/xslt/svnindex.xsl:
> Add comments that say what these files are.
Really? Long response coming up :-)
First, the indentation in the quote above is just e-mail mess.
Second, since I started committing a year or two ago, I have written an
asterisk at the start of every line and either a colon at the end of every line
or nothing.
HACKING doesn't describe multi-file comments, or starting the comment on a
separate line without a parenthesised symbol. All it gives is an example of a
single-file comment on the same line, which it separates with a colon:
* get_editor.c
(frobnicate_file): Check that file exists before frobnicating.
* twirl.h: Fix indentation.
Looking back through recent log messages, there seems to be no consistency.
Among the few people who seem to do multi-file comments at all, we have both my
and your examples above, and also all of:
* README, INSTALL,
www/index.html,
www/mailing-list-guidelines.html: Adjust for above rename.
* subversion/tests/libsvn_repos/run-repos-tests.py:
* subversion/tests/python-libs:
Delete, no longer required.
* doc/book/book/ch05.xml
* doc/book/book/ch09.xml
Use <quote> mark-up instead of quotation mark characters.
and other variations. In fact it's hard to scan through and find them because
there is so much variation.
Is it about time we wrote a log message format checker? HACKING says that the
possibility is one reason for being consistent, bus as we don't have one we
aren't consistent. Note that I don't really think we need to do so, nor that
it would be easy to make it flexible enough to satisfy us; I just like playing
with standards-enforcement tools, but only if they are under my control!
>> --- trunk/tools/xslt/svnindex.css (original)
>> +++ trunk/tools/xslt/svnindex.css Mon Jan 24 16:45:56 2005
>> @@ -1,3 +1,6 @@
>> +/* A sample style sheet for displaying the Subversion directory listing */
>> +/* that is generated by mod_dav_svn and "svnindex.xsl". */
>> +
>>
> The /* */ -style comments can span multiple lines. Don't close and
> reopen the comment like that.
Dang. I wondered whether to ask about that but didn't, and just played safe (I
searched in our source tree and we didn't have any line-spanning CSS comments).
> Oh, thanks for making the effort. :-)
Thanks for the review :-P
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Jan 25 01:38:52 2005