I am not an expert programmer (although I work in software every day). I'm more of a system designer. Dlang has really made a big difference in our little company and we are truly grateful to have it. However, one thing I miss from my PHP days (I know - script languages - Ugh), is having public comments below each manual page.

Having the public post examples, gotchas, and other helpful information made a world of difference in learning the PHP language, all the while having the "source of truth" directly above.

Just suggesting that it might help increase adoption rates (PHP is very popular). Managing comments does take time, but then so does managing this forum.

Anyway, no ideas are bad ideas, so I felt I should post. I hope it is helpful.

On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:

Personally, I don't like it. I don't think good documentation needs comments to explain the content.

The reason why it's good for PHP is mostly because of how unintuitive and inconsistent it really is sometimes.

As you said yourself, it's good for gotchas etc.

D doesn't really have any gotchas in that sense since it's much more strict, not just in the sense of its language, but also how the standard library is written.

Most gotchas in PHP stem from inconsistent function names, arguments and the fact it's dynamic typing.

D has very consistent naming of functions, order of arguments and it's static typed.

Most other language documentations don't have a comment section either and probably because they're documented well too.

While PHP has improved and keeps improving, then it still let's most of is garbage linger around.

On Wednesday, 8 June 2022 at 08:26:02 UTC, bauss wrote:

I see your point Bauss. I suppose I am not yet experienced enough with D.

Here is an example. Working with one of our programmers, he could not understand the following (sorry for my newbie simplistic example and understanding of D):

if ( a_name.exists ) ...

Where a_name is a string argument passed into the function. He felt that it was checking if the string has a value and could not understand why. It was a surprise to find that "exists" is actually a uniquely named D function that actually means "fileexists". Same with copy and remove.

Later, a more senior developer suggested we alias these names to be more readable, and easier to search for (we have a mix of D code, JS, and even our own class methods with similar names).

Maybe public comments like this within the manual could help with understanding and help improve the accessibility and adoption of D?

Regardless, D is wonderful, and we are thankful to have it. We hope D achieves widespread adoption it so that our company can rest assured that the project will live on. Sadly, a big deciding factor is risk mitigation (particularly by venture capitalists) and access to experience developers, who are all looking at this in the same way. It is very frustrating to hear "Why would we want to code in D? Who uses D?" when we know with 100% certainty that D significantly reduces our development time, and increases the reliability and maintainability of our software. And likewise, when a programmer says "I cannot understand the manual. It seems to be written for D experts only" it feels like a punch to the gut.

D is brilliant once you get into it. We will do whatever we can to help it spread.

Thank you for listening.

On Wednesday, 8 June 2022 at 18:34:20 UTC, Paul wrote:

Here is a simple Phobos trick (courtesy of Adam) that I learned after much time grieving about std.file short names.

Tip: Use static import file = std.file; instead of import std.file;

https://d.godbolt.org/z/cq5xejdTx

Now you have:

• file.read
• file.write
• file.exists

It's bad that Phobos takes over the namespace with non-descriptive names like read/write/exists, when names like fileExists/fileRead/fileWrite would be better for code completion and discoverability. And indeed, Phobos has a lot of undiscoverable things because the names don't have a prefix.

But you can keep things readable anyway with static import.

On Wednesday, 8 June 2022 at 18:34:20 UTC, Paul wrote:

Welcome to D!
Do not hesitate to speak about your experiences in the D Blog :)

WRT "exists" being difficult to discover, it's important to keep in mind that D is a generic programming language. The "exists" concept won't necessarily apply to files, which make prefixing much more desirable than embedding the "file" name directly into the function (or template) name.

As an example outside from programming, consider how domain names are organised,

toplevel = dlang.org
sub-level = forum.dlang.org

We could create a brand new domain, forumdlang.org but that's not a great idea do to. Same idea as with exists.

The basic issue is that not much has progressed with programming languages over the last century (yes I'm joking) we still use text editors to program with (IDE's are noth more than glorified text editors), and a side effect of that is searching on text strings is kinda silly if you know what I mean.

Really the best way to view a programming language is as if it were a strand of DNA, it's something to manipulate, but it has to be done carefully otherwise you end up with a lot of warts. We need much better tools, one day we may have them, but I'll probably in the grave before that ever happens.

On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:

I think that's a great idea if done properly. For example we'd have to be careful to ensure that the comments are not misleading or incorrect, the comments should NOT directly be a part of the documentation, which should always remain a separate item.

How to manage and design such a thing needs some thought, but I see no reason why it's not possible. We could for example, only allow known D members as contributors to ensure quality. We could use a database with links to the separate comments to keep the two spaces complete separate (except we do need the links in there somehow).