Date: Thu, 28 Apr 2016 16:38:00 -0600 (MDT) From: Warren Block <wblock@wonkity.com> To: Pedro Giffuni <pfg@FreeBSD.org> Cc: FreeBSD-doc@FreeBSD.org Subject: Re: Where did we lurn to spel? Message-ID: <alpine.BSF.2.20.1604281617050.82220@wonkity.com> In-Reply-To: <8bfec353-748c-68e2-ddad-fd9a79790b97@FreeBSD.org> References: <5ac139d2-a9ed-e7bf-081b-2e841f4be22a@FreeBSD.org> <alpine.BSF.2.20.1604281518580.82220@wonkity.com> <alpine.BSF.2.20.1604281536330.82220@wonkity.com> <8bfec353-748c-68e2-ddad-fd9a79790b97@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 28 Apr 2016, Pedro Giffuni wrote: > On 04/28/16 16:36, Warren Block wrote: >> On Thu, 28 Apr 2016, Warren Block wrote: >> >>> On Thu, 28 Apr 2016, Pedro Giffuni wrote: >>> >>>> Hello; >>>> >>>> I just updated locally the textproc/codespell to the latest version >>>> (bugzilla 209128 for the curious), and it finds a *crazy* amount of >>>> issues in code comments. >>>> >>>> I can't handle it on my own, indeed I got tired just be checking >>>> sys/arm ! Anyways, here is what I went "thru": >>>> >>>> https://people.freebsd.org/~pfg/patches/codespell/ >>> >>> textproc/igor finds many mistakes, and works on text files, man pages, >>> DocBook, and HTML. Use of either of these tools is optional, though. >>> >>> Note: in sys/arm/at91/if_atereg.h, it missed "deines"->"defines". >> > > Yes, I haven't really reviewed them beyond the initial replacement. > The changes kept growing and growing and I had to stop. > >> Oh, and many of these are contractions, which should be avoided anyway. > > Well the main questions are ... > > 1) Should someone brave just go ahead and commit massively > such cleanups? It is tempting. > 2) Is there a clever review process to go through these? > Phabricator with documentation team, or assume common > sense? In comments, obvious errors don't need any review. I saw one change in there that changed "safe" to "safely", but the original might have been meant as "-safe", like "multiuser-safe". Those types of changes should be reviewed, and also changes that are not to comments, like the output in the last batch. Maybe the original printf output was meant to line up. > 3) There are many common issues: is "thru" something we should > accept in comments. How about dont vs don't ? The old "be generous in what you accept and strict in what you produce" saying can apply. The code is what we produce, and comments should be as good as we can make them. "Thru" is difficult to justify. "Dont" and "cant" could be from trying to avoid an apostrophe. Just spelling out the words instead of using the contraction solves the problem. We have found in other documentation that bad sections are often copied and pasted as templates. Fixing them avoids later, bigger fixes.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.20.1604281617050.82220>