www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Season of Docs

reply Seb <seb wilzba.ch> writes:
Google recently announced the Season of Docs:

https://developers.google.com/season-of-docs

Would anyone be interested in participating as a writer or mentor?

Where do you think D has the deepest need of good technical 
documentation?
Mar 15
next sibling parent reply Dennis <dkorpel gmail.com> writes:
On Friday, 15 March 2019 at 16:52:12 UTC, Seb wrote:
 Where do you think D has the deepest need of good technical 
 documentation?
When it comes to technical documentation, the dmd codebase could really use some comments. Take these files for example: https://dlang.org/phobos/dmd_s2ir.html https://dlang.org/phobos/dmd_todt.html https://dlang.org/phobos/dmd_eh.html Eh? Those acronyms aren't immediately obvious, and there isn't a header that explains what the module is about. Not to mention the back-end, where you have such descriptive filenames as 'cod1.d' to 'cod5.d', and documentation completely missing: https://dlang.org/phobos/dmd_backend_cod1.html "Oh No! Page Not Found" This is more helpful already: https://wiki.dlang.org/DMD_Source_Guide But it is full of statements like: "Note: This section may be considerably outdated. Please bring it up to date where you can." An this gem: "Symbol - Appears to have something to do with the names used by the linker." This is what I expect to hear from a reverse engineering project, not an open source codebase. --- Secondly, the command line reference of dmd is pretty bare too https://dlang.org/dmd-windows.html -shared Generate DLL library If I interpreted https://wiki.dlang.org/Win32_DLLs_in_D correctly, it doesn't actually generate a DLL, it just disables an optimization that's not valid in DLL's. You still have to put the resulting .obj through a linker manually or add -of=mylibrary.dll. --- Finally, Dub. Possibly technical documentation isn't the solution here, but I still wanted to mention how often I go back to the json/sdl package reference trying to get Something Simple done. Build options, -settings, -requirements, -types and -configurations are mentioned. It still confuses me. More of https://github.com/dlang/dub/wiki/Cookbook would be nice. https://dub.pm/advanced_usage.html "Execute dub <command> -h for more information on these commands." Please just include all info in the docs thank you very much.
Mar 15
next sibling parent reply JN <666total wp.pl> writes:
On Friday, 15 March 2019 at 21:07:45 UTC, Dennis wrote:
 If I interpreted https://wiki.dlang.org/Win32_DLLs_in_D 
 correctly, it doesn't actually generate a DLL, it just disables 
 an optimization that's not valid in DLL's. You still have to 
 put the resulting .obj through a linker manually or add 
 -of=mylibrary.dll.

 ---

 Finally, Dub.
Also, both. I'd like to know how to create DLLs when building with dub.
Mar 16
parent reply Guillaume Piolat <first.last gmail.com> writes:
On Saturday, 16 March 2019 at 14:30:59 UTC, JN wrote:
 Also, both. I'd like to know how to create DLLs when building 
 with dub.
It's really not that complicated! # BUILD In your dub.json, use the targetType "targetType": "dynamicLibrary", Mixin that template for creating a DLL: -------------- dllmain.d -------------- // Dynamic libraries entry point. // Basically only needed on Windows, on POSIX the other entry points are sufficient. version(Windows) { template DLLEntryPoint() { const char[] DLLEntryPoint = q{ import core.sys.windows.windef; import core.sys.windows.dll; extern (Windows) BOOL DllMain(HINSTANCE hInstance, ULONG ulReason, LPVOID pvReserved) { return true; } }; } } else { template DLLEntryPoint() { const char[] DLLEntryPoint = ``; } } --------------------------------------- IMPORTANT: Use `export` for any call you want exported in your DLL! (Optional: Use some OS-specific tricks to get a static runtime instead of an annoying, shared one, for example: // Windows: There is now a new LDC flag to do this, use it instead "lflags-windows-ldc": [ "libcmt.lib", "/nodefaultlib:msvcrt.lib", "/nodefaultlib:vcruntime.lib" ], // Linux "dflags-linux-dmd": ["-defaultlib=libphobos2.a"], // OSX, not sure for DMD "dflags-osx-ldc": ["-static"], ) # CODE ## I DON'T WANT TO USE THE RUNTIME Either use -betterC, or (a bit easier) link with the runtime but never enable it. Mark your entry points "nothrow nogc", use no TLS, no global dtor/ctor, and try to live within the nogc world. ## I WANT TO USE THE RUNTIME Use LDC special ctor/dtor to call Runtime.initialize() and Runtime.finalize() https://wiki.dlang.org/LDC-specific_language_changes#LDC_global_crt_ctor_and_LDC_global_crt_dtor If you don't use them, you will need some sort of initialization entry points, or a shady lazy mechanism. AND THEN on every entry points, attach incoming threads with `thread_attachThis()` and detach them with `thread_detachThis()`. Don't keep threads attached when they have quite your dynlib and might be killed by a host program, you will suffer quite a bit if you do. Hope it helps! It has been doable for YEARS to make dynlib with D.
Mar 18
parent Guillaume Piolat <first.last gmail.com> writes:
On Monday, 18 March 2019 at 21:28:05 UTC, Guillaume Piolat wrote:
 Hope it helps! It has been doable for YEARS to make dynlib with 
 D.
Also: you don't need a .def anymore since `export` works in both LDC and DMD for Windows. It is unneeded since about 3 years.
Mar 18
prev sibling next sibling parent kevin brack <kevinbrack45 gmail.com> writes:
On Friday, 15 March 2019 at 21:07:45 UTC, Dennis wrote:
 On Friday, 15 March 2019 at 16:52:12 UTC, Seb wrote:
 [...]
When it comes to technical documentation, the dmd codebase could really use some comments. Take these files for example: https://dlang.org/phobos/dmd_s2ir.html https://dlang.org/phobos/dmd_todt.html https://dlang.org/phobos/dmd_eh.html Eh? Those acronyms aren't immediately obvious, and there isn't a header that explains what the module is about. [...]
Great thanks for this help
Mar 18
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
Sounds like a post you should put up on bugzilla.
Mar 18
prev sibling parent reply Mike Franklin <slavo5150 yahoo.com> writes:
On Friday, 15 March 2019 at 16:52:12 UTC, Seb wrote:

 Where do you think D has the deepest need of good technical 
 documentation?
The `return` and `scope` attribute (e.g. DIP25 and DIP1000) need a lot of help. In addition to the semantics themselves, there are other behaviors that need documentation: 1) Attributes are often inferred, but how and when this inference occurs is not documented. I remember playing around to try and figure it out, and I found that the even when explicitly marking something with `scope`, the compiler removed it due to the inference rules. That was alarming to me. 2) Walter introduced a convention where the first parameter of a function is treated differently than others. This behavior needs to be documented (and should be reverted, IMO). See https://github.com/dlang/dmd/pull/8504 It is critical that the developer that introduces a feature document it sufficiently. After the documentation is primed with the initial explanation, the rest of the community can inherit it and build on it. But without that initial documentation, noone else knows what to write. See https://forum.dlang.org/post/jmdlnsijowsdmiuhfrwn forum.dlang.org Mike
Mar 18
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/18/2019 6:59 PM, Mike Franklin wrote:
 I found 
 that the even when explicitly marking something with `scope`, the compiler 
 removed it due to the inference rules.  That was alarming to me.
I don't know of a case where it does that. It would be a bug.
Mar 18
parent reply Mike Franklin <slavo5150 yahoo.com> writes:
On Tuesday, 19 March 2019 at 05:10:57 UTC, Walter Bright wrote:
 On 3/18/2019 6:59 PM, Mike Franklin wrote:
 I found that the even when explicitly marking something with 
 `scope`, the compiler removed it due to the inference rules.  
 That was alarming to me.
I don't know of a case where it does that. It would be a bug.
I sent you an e-mail about it on June 28, 2018. Here's the code in the compiler that I alluded to. https://github.com/dlang/dmd/blob/25b1f0a55159d2addfc2edd5ff1de3c8c983f66e/src/dmd/typesem.d#L1358-L1363 ```D if (fparam.storageClass & STC.scope_ && !fparam.type.hasPointers() && fparam.type.ty != Ttuple) { fparam.storageClass &= ~STC.scope_; if (!(fparam.storageClass & STC.ref_)) fparam.storageClass &= ~STC.return_; } ``` The following code fails as a result: ```D void foo(scope int p); static assert(__traits(getParameterStorageClasses, foo, 0)[0] == "scope"); ``` Revisiting this just now, I realize that if I make the parameter `scope int* p` instead of `scope int p` it works fine. Maybe that is by design (yuck!), maybe it's not, I don't know because it's not sufficiently documented. Regardless, the compiler shouldn't be removing anything the user explicitly specifies. Instead, it should give the user an error. I can't submit bug reports against a non-existent specification. Without the spec, how am I supposed to know whether or not its a bug, and how is a developer supposed to know what to do for the fix? It's a no-win situation. Also, some of your DIP 1000 PRs should not have been merged because they lacked enough documentation for anyone to do a proper review, but my concerns fell on deaf ears. And just any documentation is not sufficient. To this day, you're still fielding questions on the forum because noone knows how it's supposed to work; they're just speculating. Perhaps if you documented it, others might know how to leverage it and help you with your immediate goal of improving Phobos. Mike
Mar 18
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/18/2019 11:19 PM, Mike Franklin wrote:
 Revisiting this just now, I realize that if I make the parameter `scope int*
p` 
 instead of `scope int p` it works fine.
`scope` applied to values that do not contain any references gets ignored because it applies to references. The compiler is behaving as designed.
 Also, some of your DIP 1000 PRs should not have been merged because they
lacked 
 enough documentation for anyone to do a proper review, but my concerns fell on 
 deaf ears.  And just any documentation is not sufficient.  To this day,
you're 
 still fielding questions on the forum because noone knows how it's supposed to 
 work; they're just speculating.  Perhaps if you documented it, others might
know 
 how to leverage it and help you with your immediate goal of improving Phobos.
I suggest: http://dconf.org/2017/talks/bright.html for a tutorial on the basics.
Mar 18
next sibling parent reply Mike Franklin <slavo5150 yahoo.com> writes:
On Tuesday, 19 March 2019 at 06:28:06 UTC, Walter Bright wrote:

 `scope` applied to values that do not contain any references 
 gets ignored because it applies to references. The compiler is 
 behaving as designed.
It's being removed, not ignored.
 Also, some of your DIP 1000 PRs should not have been merged 
 because they lacked enough documentation for anyone to do a 
 proper review, but my concerns fell on deaf ears.  And just 
 any documentation is not sufficient.  To this day, you're 
 still fielding questions on the forum because noone knows how 
 it's supposed to work; they're just speculating.  Perhaps if 
 you documented it, others might know how to leverage it and 
 help you with your immediate goal of improving Phobos.
I suggest: http://dconf.org/2017/talks/bright.html for a tutorial on the basics.
We need the details, not he basics. Mike
Mar 18
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 3/18/2019 11:29 PM, Mike Franklin wrote:
 We need the details, not he basics.
Most questions reveal that the basics are not known, such as the recent thread initiated by Meta. Can't dive into calculus and skip algebra. If one doesn't understand how pointers and refs are tracked, the more complex scenarios will never, ever make any sense. As I said earlier, I know the documentation needs to get better. But first I'm going to get Phobos to compile with -dip1000, since it is fairly useless if the standard library doesn't work with it.
Mar 18
prev sibling parent Nicholas Wilson <iamthewilsonator hotmail.com> writes:
On Tuesday, 19 March 2019 at 06:29:05 UTC, Mike Franklin wrote:
 On Tuesday, 19 March 2019 at 06:28:06 UTC, Walter Bright wrote:
 I suggest:

   http://dconf.org/2017/talks/bright.html

 for a tutorial on the basics.
We need the details, not he basics.
To elaborate, we need a place to point people when they have questions about how dip1000 behaves, one master document. That is not that document: it covers the basics and is coming up 2 years, things have changed and if you asked me to list them, I'd have no idea. I have vague notions about how I think it works but have nothing concrete because the documentation that exists is sparse and probably out of date. Ideally that document should be the spec, but we need to have one wherever it is.
Mar 19
prev sibling parent reply Paolo Invernizzi <paolo.invernizzi gmail.com> writes:
On Tuesday, 19 March 2019 at 06:28:06 UTC, Walter Bright wrote:
 On 3/18/2019 11:19 PM, Mike Franklin wrote:
 [...]
`scope` applied to values that do not contain any references gets ignored because it applies to references. The compiler is behaving as designed.
 [...]
I suggest: http://dconf.org/2017/talks/bright.html for a tutorial on the basics.
Would it help, not to ignore it, but raise a. compilation error, in this case? That would help comprehension of the topic - P
Mar 19
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/19/2019 12:13 AM, Paolo Invernizzi wrote:
 Would it help, not to ignore it, but raise a. compilation error, in this case?
Then generic code would have to be special cased (by the user) for it.
Mar 19
next sibling parent reply Paolo Invernizzi <paolo.invernizzi gmail.com> writes:
On Tuesday, 19 March 2019 at 07:33:28 UTC, Walter Bright wrote:
 On 3/19/2019 12:13 AM, Paolo Invernizzi wrote:
 Would it help, not to ignore it, but raise a. compilation 
 error, in this case?
Then generic code would have to be special cased (by the user) for it.
Sorry, I don't understand... I mean, raising a compiling error if scope is applied to values that do not contain any references, so that it would be ignored, because it applies to references: `foo(scope int p)` => compiler error... - P
Mar 19
parent reply Nicholas Wilson <iamthewilsonator hotmail.com> writes:
On Tuesday, 19 March 2019 at 09:37:21 UTC, Paolo Invernizzi wrote:
 On Tuesday, 19 March 2019 at 07:33:28 UTC, Walter Bright wrote:
 Then generic code would have to be special cased (by the user) 
 for it.
Sorry, I don't understand... I mean, raising a compiling error if scope is applied to values that do not contain any references, so that it would be ignored, because it applies to references: `foo(scope int p)` => compiler error...
`foo(scope T p)` => compiler error? Depends what `T` is, that is very annoying to have to deal with in generic code. That is why it is currently ignored if it does nothing. Unfortunately we can't have our cake and eat it too.
Mar 19
parent Paolo Invernizzi <paolo.invernizzi gmail.com> writes:
On Tuesday, 19 March 2019 at 10:10:27 UTC, Nicholas Wilson wrote:
 On Tuesday, 19 March 2019 at 09:37:21 UTC, Paolo Invernizzi 
 wrote:
 On Tuesday, 19 March 2019 at 07:33:28 UTC, Walter Bright wrote:
 Then generic code would have to be special cased (by the 
 user) for it.
Sorry, I don't understand... I mean, raising a compiling error if scope is applied to values that do not contain any references, so that it would be ignored, because it applies to references: `foo(scope int p)` => compiler error...
`foo(scope T p)` => compiler error? Depends what `T` is, that is very annoying to have to deal with in generic code. That is why it is currently ignored if it does nothing. Unfortunately we can't have our cake and eat it too.
Understood, thanks
Mar 19
prev sibling parent Olivier FAURE <couteaubleu gmail.com> writes:
On Tuesday, 19 March 2019 at 07:33:28 UTC, Walter Bright wrote:
 Then generic code would have to be special cased (by the user) 
 for it.
What about raising an error when scope is applied to a non-reference function parameter in non-generic code? Actually, how do compiler currently handle "this code has no effect, which is probably an error on your part, unless this is generic code" type of problems?
Mar 19