Bug 20272 – Add standard section "Limitations" to ddoc

Status
NEW
Severity
enhancement
Priority
P4
Component
dmd
Product
D
Version
D2
Platform
All
OS
All
Creation time
2019-10-06T14:34:26Z
Last change time
2024-12-13T19:05:48Z
Assigned to
No Owner
Creator
Berni
Moved to GitHub: dmd#19627 →

Comments

Comment #0 by dlang — 2019-10-06T14:34:26Z
It would be nice to have an additional section "Limitations". In this section, stuff, that does not work, but is not considered a bug, can be documented. For example: In std.zip I used it, without being aware that this is not a standard section. Among others, this section describes, that some compression methods and encryption is not supported. One more usecase: abs from std.math does not work correctly for int.min (and other signed integral types). Fixing this causes trouble or slows down the code. (Same for std.algorithm.comparison: min with NaNs). To avoid this, it's better to document the limitations. Putting this in the "Bugs" section would cause some confusions, because a bug is something, that should be fixed sooner or later. But here we already decided to not fix it.
Comment #1 by greeenify — 2019-10-06T21:44:23Z
Ddoc doesn't have pre-defined sections. It uses the colon to do so. So as long as you write sth along: Limitations: Your limitations here. This will be displayed similarly to the other "sections". Ddoc supports custom macros with which you could create a custom warning . However, it doesn't look like we'll get custom warning boxes (https://github.com/dlang/dlang.org/pull/2308).
Comment #2 by dlang — 2019-10-07T07:17:31Z
Similarly, but not identically. See discussion of https://github.com/dlang/phobos/pull/7199
Comment #3 by robert.schadek — 2024-12-13T19:05:48Z
THIS ISSUE HAS BEEN MOVED TO GITHUB https://github.com/dlang/dmd/issues/19627 DO NOT COMMENT HERE ANYMORE, NOBODY WILL SEE IT, THIS ISSUE HAS BEEN MOVED TO GITHUB