D6326: gendoc: group commands by category in man page and HTML help

[martinvonz (Martin von Zweigbergk)]

martinvonz added inline comments.

INLINE COMMENTS

> Sietse wrote in gendoc.py:188
> Passing `h=h, cmdtable=cmdtable` as default args is to make it obvious to the reader which data the function depends on. I realize it can also silently close over the variables in the outer scope, but I think this helps legibility.
> 
> Other places in the Mercurial codebase that define an inner function, and make a captured value obvious by passing it as a default argument:
> 
> - `def commithook` inside `def commit` in `localrepo.py`
> - `def one` inside `def _showcompatlist` in `templateutil.py` (edge case, as the default arg is actually overridden once)
> - `def doit` inside `def debugdiscovery` in `debugcommands.py
> 
> I'd say leave this as is, but I'll let you make the call and follow that.

Interesting examples.

I found the `commithook()` quite confusing. I've sent https://phab.mercurial-scm.org/D6336 to remove the arguments from it.

As you said, the `def one`argument is overridden in one place, so I don't think that's a good comparison.

The `def doit` actually uses the `remote=remote` as a trick for creating the variable in local scope.

Even if there are a few more valid cases, the vast majority seems to be just accessing the variables from the closure.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6326

To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel