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 2019
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 2019
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 2019
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!




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"],

)







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.




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 2019
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 2019
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 2019
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
Sounds like a post you should put up on bugzilla.
Mar 18 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019
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 2019