digitalmars.D.bugs - [Issue 16103] New: DDOC module-level function list descriptions
- via Digitalmars-d-bugs (43/43) May 30 2016 https://issues.dlang.org/show_bug.cgi?id=16103
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 puremagic.com Reporter: zorael 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. --
May 30 2016