[Issue 16103] New: DDOC module-level function list descriptions refer to unknown parameter names

[via Digitalmars-d-bugs]

https://issues.dlang.org/show_bug.cgi?id=16103

          Issue ID: 16103
           Summary: DDOC module-level function list descriptions refer to
                    unknown parameter names
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: minor
          Priority: P1
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: zorael at gmail.com

They make sense when you're reading the individual pages generated for the
functions themselves, but not so much in the lists on the module's page.
They're... specific, not generic enough.

Some cherry-picked examples:


Page:        https://dlang.org/library/core/atomic.html
Function:    atomicLoad
Description: "Performs the binary operation 'op' on val using 'mod' as the
modifier."
(...op? mod?)

Page:        https://dlang.org/library/core/atomic.html
Function:    cas
Description: "Stores 'writeThis' to the memory referenced by 'here' if the
value referenced by 'here' is equal to 'ifThis'. This operation is both
lock-free and atomic."
(...writeThis, here, ifThis?)

Page:        https://dlang.org/library/std/concurrency.html
Function:    spawn
Description: "Starts fn(args) in a new logical thread."
(...fn, args?)

Page:        https://dlang.org/library/std/concurrency.html
Function:    yield
Description: "Yields a value of type T to the caller of the currently executing
generator."
(...type T?)


I don't know of any good solutions. The list is a good way to roughly outline
the functions in the module, but seeing the behaviour described in terms of
'type T' and 'fn(args)' is a trap for young players and only makes sense if you
already have an idea of how they work.

--