Re: [PATCH v2] Documentation: Refactored watchdog old doc

[Guenter Roeck <linux@roeck-us.net>]

On Fri, Apr 10, 2026 at 10:45:01AM -0600, Jonathan Corbet wrote:
> Guenter Roeck <linux@roeck-us.net> writes:
> 
> > On Fri, Apr 10, 2026 at 12:58:11PM +0530, Sunny Patel wrote:
> >> Good Point. So again revisited the watchdog core
> >> api and list out the deprecated one and marked
> >> as deprecated in doc and also mentioned it just
> >> for legacy driver and not for newer one.
> >> 
> >> As someof the legacy driver still have reference 
> >> to old api so just marked as deprecated in doc.
> >> 
> >> Also checked with other watchdog related api
> >> which are deprecated in driver but still present 
> >> in doc but didn't find any.
> >> 
> >> ---
> >
> > The above would show up as commit message, there is no change log, and
> > this e-mail was sent as response to v1. And I can see that without even
> > looking at the patch itself.
> >
> > That makes me wonder what Documentation/process/submitting-patches.rst
> > is useful for. No one seems to bother reading it. We might as well
> > just remove it.
> 
> It's good to point people at.
> 
> I do think it needs a serious rewrite to, among other things, turn it
> into less of an intimidating tome.  On my list of things to do.  Now if
> I could only buy a larger drive to hold that whole list...
> 
Let's have some fun:

1st AI prompt:

You are an experienced Linux kernel developer and an AI prompt expert.
Read linux/Documentation/process/submitting-patches.rst and generate an
AI prompt file named review.md which can be used by an AI agent to review
a patch submission and determine if it follows the guidance in
submitting-patches.rst.

2nd AI prompt:

Using @review.md, review the patch in index.html, which targets the
repository in the linux/ directory. Provide review output in review.log.

Result is below (raw file as generated by the AI agent, not reformatted).

Guenter

---
Status: NEEDS WORK

Summary:
The patch updates the watchdog API documentation by marking deprecated ioctls and adding descriptions for features like MAGICCLOSE and PRETIMEOUT. While the technical content is useful, the patch requires revisions to the commit 
message and documentation text to fix typos, grammatical errors, and formatting issues.

Detailed Findings:
1. Commit Message & Description:
   - The description starts with conversational filler ("Good Point. So again revisited...") which should be removed.
   - The message is not written in the imperative mood (e.g., use "Mark WDIOC_GETTEMP as deprecated" instead of "Revisited... and marked...").
   - Typos in the commit message: "someof" (some of), "Reierate" (Reiterate).
   - The subject line "Documentation: Refactored watchdog old doc" should use the imperative mood: "Documentation: Refactor watchdog documentation".

2. Technical Content & Style:
   - Several typos in the documentation text:
     - "reboot tiemout" -> "reboot timeout" (Multiple occurrences).
     - "characted 'V'" -> "character 'V'".
     - "small number if legacy drivers" -> "small number of legacy drivers".
   - Grammatical/Formatting issues:
     - Missing space: "WDIOS_DISABLECARD,this" -> "WDIOS_DISABLECARD, this".
     - Inconsistent capitalization: "USE WDIOC_SETPRETIMEOUT" should be "Use WDIOC_SETPRETIMEOUT".
     - "New Drivers" should be "New drivers".
   - The patch results in "No newline at end of file" for Documentation/watchdog/watchdog-api.rst.

3. Canonical Patch Format:
   - The patch follows the basic canonical format (Subject, From, Sign-off, separators, changelog, and diffstat are all present).

Actionable Advice:
1. Rewrite the commit message to be professional and in the imperative mood. Remove any conversational references to previous discussions.
2. Perform a spell-check on the documentation changes. Specifically, fix "tiemout", "characted", and "if" (where "of" was intended).
3. Ensure proper spacing after punctuation (e.g., after the comma in the WDIOS_DISABLECARD description).
4. Add a newline at the end of Documentation/watchdog/watchdog-api.rst.
5. Use consistent sentence-case for instructions (e.g., "Use" instead of "USE").