www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Documentation Improvement Initiative

reply Mike Parker <aldacron gmail.com> writes:
Preliminary discussions are underway for a new event to encourage 
improvements to documentation across the D ecosystem. I can't 
provide any details yet because the details aren't yet fixed. I 
don't even know for sure it's going to happen.

However, the best way to make it happen is for us to have a solid 
set of well-defined documentation tasks. Putting that together is 
going to require help from the community. All of us have 
encountered areas where improvement is needed in the spec, the 
Phobos docs, and docs for dub, vibe.d, and many other tools and 
projects around the D ecosystem. Some of it has made it into 
Bugzilla (which will be mined for material), but much of it has 
been buried in the forum archives or evaporated into the ether 
from the IRC/Discord/Slack channels.

This thread is a place to collect your documentation pain in one 
place. I'm about to publish a blog post announcing this (a few 
minutes after I hit 'Send' on this post):

http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

As I mention there, we need you to be as specific as you can. 
What, specifically, is missing? What is unclear? What is 
incorrect? Give as much detail as you can. We want to be able to 
gather this info and define specific documentation tasks that 
anyone can step in and complete with the information provided.

Any project in the D ecosystem is fair game. So please help us 
out and tell us how D documentation can be improved for you.

If you feel the urge to wax philosophical on something you see 
here, please start a new thread and do all the philosophical 
waxing you want there. Let's keep this one focused on listing 
specific documentation issues. Do feel free to expand on any post 
here with information you think is relevant.

Thanks!
Feb 17 2020
next sibling parent bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:


 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/


This is a working link:

https://dlang.org/blog/2020/02/17/news-update-swag-platforms-documentation-help-and-more/
Feb 17 2020
prev sibling next sibling parent reply bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:


 As I mention there, we need you to be as specific as you can. 
 What, specifically, is missing? What is unclear? What is 
 incorrect? Give as much detail as you can. We want to be able 
 to gather this info and define specific documentation tasks 
 that anyone can step in and complete with the information 
 provided.


Sorry for this not being more specific, but we need a version of 
Rust's "The Cargo Book" for D:
https://doc.rust-lang.org/cargo/
The reason I can't be more specific is because I don't use Dub 
except when doing so is trivial.

We need documentation in particular on using Dub with mixed 
language projects. The obvious case is C and D, but one of our 
strengths is interoperability with basically all languages, so we 
should have examples showing how to use Dub with projects 
containing Fortran, Python, Lua, etc.
Feb 17 2020
parent reply Panke <tobias pankrath.net> writes:
On Monday, 17 February 2020 at 12:52:09 UTC, bachmeier wrote:

 Sorry for this not being more specific, but we need a version 
 of Rust's "The Cargo Book" for D:
 https://doc.rust-lang.org/cargo/
 The reason I can't be more specific is because I don't use Dub 
 except when doing so is trivial.

 We need documentation in particular on using Dub with mixed 
 language projects. The obvious case is C and D, but one of our 
 strengths is interoperability with basically all languages, so 
 we should have examples showing how to use Dub with projects 
 containing Fortran, Python, Lua, etc.


I'd second this. Figuring out how sub packages work, how to 
structure a project into different interdependent sub packages, 
how to fetch dependencies (dub upgrade does not work recursively 
:() took way too long coming back to D.

Generally a bit of best practice guidelines would be useful, see 
for example the my current question in the learn forum.
Feb 17 2020
parent reply Martin Tschierschke <mt smartdolphin.de> writes:
On Monday, 17 February 2020 at 13:55:57 UTC, Panke wrote:
[...]

 We need documentation in particular on using Dub with mixed 
 language projects. The obvious case is C and D, but one of our 
 strengths is interoperability with basically all languages, so 
 we should have examples showing how to use Dub with projects 
 containing Fortran, Python, Lua, etc.


 I'd second this. Figuring out how sub packages work, how to 
 structure a project into different interdependent sub packages, 
 how to fetch dependencies (dub upgrade does not work 
 recursively :() took way too long coming back to D.

 Generally a bit of best practice guidelines would be useful, 
 see for example the my current question in the learn forum.


Yes better docs for DUB!
With as many - as possible - use case examples.
Feb 18 2020
parent reply Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com> writes:
I think there are two ways of looking at the documentation: from 
the expert's eyes and the beginner's eyes.
I can provide feedback from the latter:
It takes some time to learn how to navigate in the library 
reference. But this comes with time. (and also with my 
inpatiance, since I am the "click a lot, read in detail later" 
type of guy).
What I lacked most was Ali's book. It answered many questions 
(especially regarding ranges). So for beginners, a more detailed 
tutorial (or a more prominent link to Ali's book) would be great.
Yes, sometimes, I find something in the wiki. There are some 
tutorials and some cookbooks. However, the information is 
scattered, sometimes outdated. Scattering of the information is 
even worse if I think about random tutorials or blogs on the 
internet.
The language reference is sometimes challenging to read (again 
for beginners). They have essential examples, but if you don't 
have the experience, it is sometimes tough to utilize the 
provided information and incorporate it into your code. My 
workflow usually involves a simple feature, which I then try to 
use; however, a simple one-liner does not cover my problem. On 
the other hand, too exhaustive examples will clutter the 
documentation.

For beginners, a more used wiki with concentrated information 
would be great.
However this is a D-Community solution. (and maybe i am wrong. 
Maybe the wiki is great and I am not long enough around to read 
it threw).
Feb 18 2020
parent bachmeier <no spam.net> writes:
On Tuesday, 18 February 2020 at 15:42:18 UTC, Jan Hönig wrote:

 For beginners, a more used wiki with concentrated information 
 would be great.


I strongly agree with this. D's website is oriented towards 
search, which is a good way to find information if you know what 
you're looking for, but that's hardly optimal for a beginner. For 
some reason our wiki isn't used much, so we only have ourselves 
to blame.

Maybe part of a documentation improvement initiative is finding 
ways to encourage wiki contributions contribute more to the wiki. 
Maybe it's because people think you need special authority to 
post things there. Honestly, there's a lot of stuff in the learn 
forum that deserves to be organized and put on the wiki IMO.

The important question is: What is not on the wiki that should be 
there?
Feb 18 2020
prev sibling next sibling parent reply bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place.


The documentation for cross compiling/linking using LDC isn't 
exactly what I'd call user friendly. It would really help to have 
a complete example so that someone can be up and running within 
five minutes. It would also be nice to have an example that 
avoids Dub altogether, and to the extent that examples do use 
Dub, they're complete and can be used by a beginner to the 
language (so at least brief explanations of Dub usage is 
explained, with links to proper documentation).
Feb 17 2020
parent bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 15:01:32 UTC, bachmeier wrote:

 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place.


 The documentation for cross compiling/linking using LDC isn't 
 exactly what I'd call user friendly. It would really help to 
 have a complete example so that someone can be up and running 
 within five minutes. It would also be nice to have an example 
 that avoids Dub altogether, and to the extent that examples do 
 use Dub, they're complete and can be used by a beginner to the 
 language (so at least brief explanations of Dub usage is 
 explained, with links to proper documentation).


Sorry, forgot the link to the page that should be improved:
https://wiki.dlang.org/Cross-compiling_with_LDC
Feb 17 2020
prev sibling next sibling parent reply bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place.


I once tried to use std.socket:
https://dlang.org/phobos/std_socket.html

Although it does link to a couple of examples, they don't have 
any explanation, so I gave up. An example where you're up and 
running in five minutes using Dub would be really nice. It's 
pretty clear that the documentation for std.socket assumes the 
user has learned sockets programming in another language before 
coming to D. We should remove that prerequisite.
Feb 17 2020
next sibling parent reply Andre Pany <andre s-e-a-p.de> writes:
On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:

 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place.


 I once tried to use std.socket:
 https://dlang.org/phobos/std_socket.html

 Although it does link to a couple of examples, they don't have 
 any explanation, so I gave up. An example where you're up and 
 running in five minutes using Dub would be really nice. It's 
 pretty clear that the documentation for std.socket assumes the 
 user has learned sockets programming in another language before 
 coming to D. We should remove that prerequisite.


Adam D. Ruppe wrote a very good socket tutorial. You can find it 
here 
http://dpldocs.info/this-week-in-d/Blog.Posted_2019_11_11.html

Kind regards
Andre
Feb 17 2020
parent bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 18:48:25 UTC, Andre Pany wrote:

 On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:

 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place.


 I once tried to use std.socket:
 https://dlang.org/phobos/std_socket.html

 Although it does link to a couple of examples, they don't have 
 any explanation, so I gave up. An example where you're up and 
 running in five minutes using Dub would be really nice. It's 
 pretty clear that the documentation for std.socket assumes the 
 user has learned sockets programming in another language 
 before coming to D. We should remove that prerequisite.


 Adam D. Ruppe wrote a very good socket tutorial. You can find 
 it here 
 http://dpldocs.info/this-week-in-d/Blog.Posted_2019_11_11.html

 Kind regards
 Andre


That looks pretty good. It would have to be incorporated into our 
official docs though, at least by providing a link.
Feb 17 2020
prev sibling next sibling parent JN <666total wp.pl> writes:
On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:

 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place.


 I once tried to use std.socket:
 https://dlang.org/phobos/std_socket.html

 Although it does link to a couple of examples, they don't have 
 any explanation, so I gave up. An example where you're up and 
 running in five minutes using Dub would be really nice. It's 
 pretty clear that the documentation for std.socket assumes the 
 user has learned sockets programming in another language before 
 coming to D. We should remove that prerequisite.


I think one of these could be incorporated as an example, either 
Adam's or Ali's code:

https://forum.dlang.org/thread/cexeumxikeovazyotkfl forum.dlang.org

I always use those when starting a new D networked project.
Feb 17 2020
prev sibling parent Daren Scot Wilson <darenw darenscotwilson.com> writes:
On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:

 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place.


 I once tried to use std.socket:
 https://dlang.org/phobos/std_socket.html

 Although it does link to a couple of examples, they don't have 
 any explanation, so I gave up. An example where you're up and 
 running in five minutes using Dub would be really nice. It's 
 pretty clear that the documentation for std.socket assumes the 
 user has learned sockets programming in another language before 
 coming to D. We should remove that prerequisite.



I am exactly such a person today!  The last time I did anything 
with sockets was 15 (?) years ago, and was very basic, and only 
for part of one day.

This week, I wanted to toss together a quickie tool to send some 
test data in binary over UDP to another machine.  I had to forget 
about the "quickie" part of that.

All the info I need about D and its libraries is there, but often 
details are hard to find if I don't already know the name of the 
module to look in. More examples would help. Just basic usage 
examples, not too basic, but enough to do something simple.

Running off somewhere else to learn UDP sockets in C or Python or 
whatever then coming back isn't my idea of efficiency.  Would-be 
users of D coming from science, engineering, fine arts, 
economics, robotics, or wherever, are likely to be interested in 
the good features of D but unlikely to want to learn another 
language to understand some feature, such as sockets.

D documentation shouldn't try to explain these sorts of things 
from scratch, of course, but a few of the very fundamental ideas 
need to be shown in an example and a few words.
May 07 2020
prev sibling next sibling parent jxel <jxel gmall.com> writes:
Literally nothing in core.stdc has documentation. Would rather 
have the documentation be there when you auto complete or 'go to 
definition' in an editor.

Same with system libraries in core.sys. What's worse there is 
that the parameter names for the functions are just 'a', 'b', 
'c', etc... Instead of the name of the actual argument.
Feb 17 2020
prev sibling next sibling parent RazvanN <razvan.nitu1305 gmail.com> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:


The elephant in the room is the DMD codebase. Examples:

1. https://dlang.org/phobos/dmd_apply.html

Empty page, with no explanation of what is the purpose of the page

2. https://dlang.org/phobos/dmd_attrib.html

Most of the documentation is non-existent, lacking or 
insufficient to understand what happend

3. https://dlang.org/phobos/dmd_expression.html

Most classes have no explanation. I would expect that each class 
would be followed by some pieces of code that highlight to what 
code the class maps

4. https://dlang.org/phobos/dmd_traits.html

It's missing documentation for the single most important function 
in the file: semanticTraits which does semantic analysis for 
`__traits()`

These are just a few examples, but the dmd codebase is full of 
such examples. In addition, now that dmd as a library is 
available, things are worse because people have no way of using 
it effectively since they cannot understand what's happening 
there. Moreover, it is impossible to attract new contributors 
when a complex piece of software is severely underdocumented.

Besides documenting this code, I think it is necessary in some 
situations to refactor the code so that we can highlight the 
documentation. For example, the traits file in dmd (link number 
4) contains a single function `semanticTraits` which has 1500 
lines of code and contains the whole traits semantic logic 
organized as if/else branches. The documentation for those 
branches will not be publicly available, so we must refactor the 
code to use separate functions. This will make the code cleaner 
and help us with documentation which is a great plus.
I gave this example because it is typical for a lot of situations 
in the dmd codebase. So not only it is a great chance to improve 
the documentation of dmd, but also to make the codebase more 
modern.



 Feb 17 2020



prev sibling next sibling parent reply Panke <tobias pankrath.net>  writes:


On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 If you feel the urge to wax philosophical on something you see 
 here, please start a new thread and do all the philosophical 
 waxing you want there. Let's keep this one focused on listing 
 specific documentation issues. Do feel free to expand on any 
 post here with information you think is relevant.

 Thanks!


A timeline of current language changes would be nice. What is 
currently deprecated and when will it be removed, what can be 
found under `dmd -preview=?` and when it will be part of the 
language or if it is just under consideration.



 Feb 18 2020



  parent  James Blachly <james.blachly gmail.com>  writes:


On 2/18/20 10:59 AM, Panke wrote:

 A timeline of current language changes would be nice. What is currently 
 deprecated and when will it be removed, what can be found under `dmd 
 -preview=?` and when it will be part of the language or if it is just 
 under consideration.


Seconding this as CRITICAL as the language evolves



 Feb 18 2020



prev sibling next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx>  writes:


On Mon, Feb 17, 2020 at 12:16:26PM +0000, Mike Parker via Digitalmars-d wrote:
[...]

 This thread is a place to collect your documentation pain in one
 place. I'm about to publish a blog post announcing this (a few minutes
 after I hit 'Send' on this post):
 
 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/
 
 As I mention there, we need you to be as specific as you can. What,
 specifically, is missing? What is unclear? What is incorrect? Give as
 much detail as you can. We want to be able to gather this info and
 define specific documentation tasks that anyone can step in and
 complete with the information provided.


[...]

std.windows.registry does not have any docs.  The website doesn't even
have a link for it! (And going to the page by editing the URL manually
brings up a page with no docs for any symbol.)

Note that the code itself *does* have docs; the problem is that the
website docs are generated on Posix but all symbols in this module are
under version(Windows).  We seriously need to generate docs for *all*
platforms, not just the one being used to generate them!

(The other std.windows.* modules have the version(StdDoc) hack, but
that's seriously b0rken because what's used to generate docs is
different from what actually compiles, meaning any mistakes will not be
caught by CI, code examples are not compile-checked, etc..)


T

-- 
People tell me that I'm skeptical, but I don't believe them.



 Feb 18 2020



  parent reply Adam D. Ruppe <destructionator gmail.com>  writes:


On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh wrote:

 std.windows.registry does not have any docs.


http://dpldocs.info/locate/?searchTerm=std.windows.registry


This is one of the big reasons why I decided *against* using dmd 
for my doc generation thing - it actually follows `version` rules 
which is necessary for compiling, but a bad thing for docs! So 
instead I did a separate parser.

Join me and together we rule the Dalaxy with good documentation!



 Feb 18 2020



  parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx>  writes:


On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via Digitalmars-d wrote:

 On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh wrote:

 std.windows.registry does not have any docs.


 
 http://dpldocs.info/locate/?searchTerm=std.windows.registry
 
 
 This is one of the big reasons why I decided *against* using dmd for
 my doc generation thing - it actually follows `version` rules which is
 necessary for compiling, but a bad thing for docs! So instead I did a
 separate parser.
 
 Join me and together we rule the Dalaxy with good documentation!


Maybe we should *replace* the current docs with dpldocs... Make dpldocs
the official doc system. Throw out the current half-baked stuff...


T

-- 
Without outlines, life would be pointless.



 Feb 18 2020



  parent reply Les De Ridder <les lesderid.net>  writes:


On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:

 On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via 
 Digitalmars-d wrote:

 On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh wrote:

 std.windows.registry does not have any docs.


 
 http://dpldocs.info/locate/?searchTerm=std.windows.registry
 
 
 This is one of the big reasons why I decided *against* using 
 dmd for my doc generation thing - it actually follows 
 `version` rules which is necessary for compiling, but a bad 
 thing for docs! So instead I did a separate parser.
 
 Join me and together we rule the Dalaxy with good 
 documentation!


 Maybe we should *replace* the current docs with dpldocs... Make 
 dpldocs the official doc system. Throw out the current 
 half-baked stuff...


 T


I frankly much prefer the current docs over dpldocs. While dpldocs
might be technically superior, the UI is quite bad, it looks cold 
and
cluttered to me. A large part of this can probably be fixed 
through CSS
changes, though.



 Feb 19 2020



 next sibling parent  Paolo Invernizzi <paolo.invernizzi gmail.com>  writes:


On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
wrote:

 On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:

 On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via 
 Digitalmars-d wrote:

 [...]


 Maybe we should *replace* the current docs with dpldocs... 
 Make dpldocs the official doc system. Throw out the current 
 half-baked stuff...


 T


 I frankly much prefer the current docs over dpldocs. While 
 dpldocs
 might be technically superior, the UI is quite bad, it looks 
 cold and
 cluttered to me. A large part of this can probably be fixed 
 through CSS
 changes, though.


+1 ...



 Feb 19 2020



prev sibling next sibling parent  bachmeier <no spam.net>  writes:


On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
wrote:

 On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:

 On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via 
 Digitalmars-d wrote:

 On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh 
 wrote:

 std.windows.registry does not have any docs.


 
 http://dpldocs.info/locate/?searchTerm=std.windows.registry
 
 
 This is one of the big reasons why I decided *against* using 
 dmd for my doc generation thing - it actually follows 
 `version` rules which is necessary for compiling, but a bad 
 thing for docs! So instead I did a separate parser.
 
 Join me and together we rule the Dalaxy with good 
 documentation!


 Maybe we should *replace* the current docs with dpldocs... 
 Make dpldocs the official doc system. Throw out the current 
 half-baked stuff...


 T


 I frankly much prefer the current docs over dpldocs. While 
 dpldocs
 might be technically superior, the UI is quite bad, it looks 
 cold and
 cluttered to me. A large part of this can probably be fixed 
 through CSS
 changes, though.


I agree. It's not a problem for me, but if it's the *official* 
documentation generator, it needs a better design. That shouldn't 
take much though. These days there are tons of static site 
generators, so it's easy to steal a design.



 Feb 19 2020



prev sibling  parent reply Adam D. Ruppe <destructionator gmail.com>  writes:


On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
wrote:

 A large part of this can probably be fixed through CSS changes, 
 though.


If you send me a concept sketch or css suggestion we can talk 
about it.

I have a somewhat long list of things that I'm not happy with, 
though any fix for those needs to not break the things that do 
work... and the problem I've had isn't so much identifying the 
problems as finding the solutions.

So I'd prefer specific fix ideas over general "I don't like this" 
things.



 Feb 19 2020



 next sibling parent reply bachmeier <no spam.net>  writes:


On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe 
wrote:

 On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
 wrote:

 A large part of this can probably be fixed through CSS 
 changes, though.


 If you send me a concept sketch or css suggestion we can talk 
 about it.

 I have a somewhat long list of things that I'm not happy with, 
 though any fix for those needs to not break the things that do 
 work... and the problem I've had isn't so much identifying the 
 problems as finding the solutions.

 So I'd prefer specific fix ideas over general "I don't like 
 this" things.


If it's going to become the official documentation, it needs to 
match the existing website 100%. That's not currently the case.

The other thing that immediately stands out to me when I click a 
random project's documentation, like this:
https://hunt-database.dpldocs.info/hunt.html
is that the page doesn't contain a lot of information. This
https://dlang.org/phobos/std_range.html
is much more approachable. Maybe that can be avoided, I don't 
know, but the first example doesn't bring me joy.

I'm not the biggest fan of all the information on this page 
(comparing apples to apples now):
http://dpldocs.info/experimental-docs/std.range.html
I think it would be better to be able to click to expand if you 
want information about types. iota, for instance, is cluttered 
but the extra information doesn't bring much to the table.

I also don't understand why the functions are listed twice.



 Feb 19 2020



  parent reply Adam D. Ruppe <destructionator gmail.com>  writes:


On Wednesday, 19 February 2020 at 17:09:02 UTC, bachmeier wrote:

 The other thing that immediately stands out to me when I click 
 a random project's documentation, like this:
 https://hunt-database.dpldocs.info/hunt.html
 is that the page doesn't contain a lot of information.


That's because the author of that project wrote near-zero 
documentation. I can't fix that myself.


 I think it would be better to be able to click to expand if you 
 want information about types. iota, for instance, is cluttered 
 but the extra information doesn't bring much to the table.


Yeah, the members list is one of the things I'm not really happy 
with.

I'm not sure there's any real value in separating out classes, 
structs, enums, etc., and I do think it shows too much there.

I did just fix a bug in it so it doesn't duplicate those function 
prototypes (actually the technical difference was they had 
separate constraints, but sine that isn't visible here it looked 
like a total duplicate and waste) anymore.

But the other worry is the information on the right. Part of this 
is that the documentation in the source doesn't really follow the 
spec. https://dlang.org/spec/ddoc.html#summary says the first 
thing in a ddoc comment is supposed to be a short summary. Then 
you put in a paragraph break and write the rest of your details.

Though maybe I can just limit the size on my side though.

But yeah this members list is one of the things I was never 
actually happy with so I'm open to any ideas to change it, 
potentially up to a total replacement.

if you refresh this now you can see some changes:
http://dpldocs.info/experimental-docs/std.range.html



 I also don't understand why the functions are listed twice.


Ddoc's limitations led to the authors writing it out by hand, but 
then my  generator auto-generates a list and doesn't realize the 
hand-written list is there (and even if it did, the hand written 
list is frequently incomplete!).

So now it has both.

The ddox version on the official site does basically the same 
thing for the same reason:

  https://dlang.org/library/std/range.html

ddox strips types out of its listing on the left, something I've 
also considered, but I find types to be really useful...


My generator also has the ability to group functions into 
categories

http://dpldocs.info/experimental-docs/arsd.nanovega.html#members

but that requires a tag be added to the source and Phobos does 
the hand-written tables instead of tags on the functions since 
ddoc doesn't support tagging anyway. so bleh.



 Feb 19 2020



  parent  John Colvin <john.loughran.colvin gmail.com>  writes:


On Wednesday, 19 February 2020 at 20:47:11 UTC, Adam D. Ruppe 
wrote:


 My generator also has the ability to group functions into 
 categories

 http://dpldocs.info/experimental-docs/arsd.nanovega.html#members

 but that requires a tag be added to the source and Phobos does 
 the hand-written tables instead of tags on the functions since 
 ddoc doesn't support tagging anyway. so bleh.


That's pretty cool



 Feb 20 2020



prev sibling next sibling parent reply Les De Ridder <les lesderid.net>  writes:


On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe 
wrote:

 On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
 wrote:

 A large part of this can probably be fixed through CSS 
 changes, though.


 [...]

 So I'd prefer specific fix ideas over general "I don't like 
 this" things.


I don't particularly feel like bikeshedding too much about what it
should look like, I'm not great at UI design. That said, I think 
the
design of the current official docs is pretty good and fits in 
well with
the rest of dlang.org.

Some of the things that I think would help: add more padding, 
simplify
the colour scheme, use monospaced fonts, use less bold fonts.

Examples after fiddling around with the CSS for a couple minutes:

Before: https://u.sicp.me/m2sMw.png
After: https://u.sicp.me/ieJht.png
Official docs: https://u.sicp.me/kzZTg.png

(Maybe we ought to move this to a seperate thread or to 
IRC/Slack?)



 Feb 19 2020



  parent  Mike Parker <aldacron gmail.com>  writes:


On Thursday, 20 February 2020 at 00:11:58 UTC, Les De Ridder 
wrote:

 On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe 
 wrote:

 On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
 wrote:




Guys, can we please keep this thread focused on specific 
documentation issues like I asked? I want as many issues as we 
can get and to be able to go through the thread without wading 
through lots of off topic discussion.

Thanks!



 Feb 19 2020



prev sibling  parent reply John Colvin <john.loughran.colvin gmail.com>  writes:


On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe 
wrote:

 On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
 wrote:

 A large part of this can probably be fixed through CSS 
 changes, though.


 If you send me a concept sketch or css suggestion we can talk 
 about it.

 I have a somewhat long list of things that I'm not happy with, 
 though any fix for those needs to not break the things that do 
 work... and the problem I've had isn't so much identifying the 
 problems as finding the solutions.

 So I'd prefer specific fix ideas over general "I don't like 
 this" things.


My general problem with most docs is that I actually prefer the 
"one big page" approach per-module. The practical relationships 
between functions, objects, methods and members often aren't 
hierarchical and it's so much easier to get an overview by 
scrolling through a larger page.

The same reason applies to why I almost never use code-folding in 
an editor.



 Feb 20 2020



  parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx>  writes:


On Thu, Feb 20, 2020 at 10:21:25AM +0000, John Colvin via Digitalmars-d wrote:
[...]

 My general problem with most docs is that I actually prefer the "one
 big page" approach per-module. The practical relationships between
 functions, objects, methods and members often aren't hierarchical and
 it's so much easier to get an overview by scrolling through a larger
 page.
 
 The same reason applies to why I almost never use code-folding in an
 editor.


Yeah, the one-page doc is nicer because you can actually search for
keywords on the page and find what you want, instead of having to click
on who knows how many links just to get to the one place you already
know is there.


T

-- 
Marketing: the art of convincing people to pay for what they didn't need before
which you fail to deliver after.



 Feb 21 2020



  parent  Adam D. Ruppe <destructionator gmail.com>  writes:


On Friday, 21 February 2020 at 19:27:51 UTC, H. S. Teoh wrote:

 Yeah, the one-page doc is nicer because you can actually search 
 for keywords on the page and find what you want, instead of 
 having to click on who knows how many links just to get to the 
 one place you already know is there.


But on the other hand, external search engines do a very poor job 
actually getting you there.

That's why my site does a bit of both: dpldocs.info/std.ascii 
will search for you, the module page has an overview listing of 
members, and you have clear URLs for outside linking.

Even on the current dlang.org site, the ddox versions are more 
likely to pop up on outside web searches than the ddoc single 
page one!



 Feb 21 2020



prev sibling next sibling parent reply Mathias Lang <pro.mathias.lang gmail.com>  writes:


On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D ecosystem. 
 I can't provide any details yet because the details aren't yet 
 fixed. I don't even know for sure it's going to happen.

 However, the best way to make it happen is for us to have a 
 solid set of well-defined documentation tasks. Putting that 
 together is going to require help from the community. All of us 
 have encountered areas where improvement is needed in the spec, 
 the Phobos docs, and docs for dub, vibe.d, and many other tools 
 and projects around the D ecosystem. Some of it has made it 
 into Bugzilla (which will be mined for material), but much of 
 it has been buried in the forum archives or evaporated into the 
 ether from the IRC/Discord/Slack channels.

 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

 As I mention there, we need you to be as specific as you can. 
 What, specifically, is missing? What is unclear? What is 
 incorrect? Give as much detail as you can. We want to be able 
 to gather this info and define specific documentation tasks 
 that anyone can step in and complete with the information 
 provided.

 Any project in the D ecosystem is fair game. So please help us 
 out and tell us how D documentation can be improved for you.

 If you feel the urge to wax philosophical on something you see 
 here, please start a new thread and do all the philosophical 
 waxing you want there. Let's keep this one focused on listing 
 specific documentation issues. Do feel free to expand on any 
 post here with information you think is relevant.

 Thanks!


1. Dub documentation

DUB needs much, much better documentation. Especially cookbooks 
(there's already some, but it is not accessible enough IMO). 
Example of how to structure a project (writing a library with an 
executable, writing a project with examples that are separate and 
compile, writing a client/server app or any two apps linked 
together, writing a project that interface with C/C++, writing a 
project that use some preprocessor, e.g. dtoh, etc..).

Some of this documentation will *also* require fixes to Dub (e.g. 
https://github.com/dlang/dub/issues/1474 for anything using 
preprocessor). There is a feature that allows a project to 
provide skeleton for apps using it, it might also be useful to 
try to do it with a few projects.

2. DMD documentation

Inexistent. Enough said.

3. C++ interfacing documentation

The documentation for interfacing with C++ is ridiculously 
outdated (e.g. it says that operators overloads are not callable 
from D). I am currently rewriting it.

Also, some other features are not documented. It would be helpful 
to have a language expert going over it and see what missing 
(e.g. yesterday I found out `pragma(crt_{con,de}structor)` was 
missing, despite being in the language since 2018-01-01). But I 
don't have specific example of missing features ATM.

4. Documentation history

https://issues.dlang.org/show_bug.cgi?id=20588

5. More pattern documentation

Some of https://github.com/zhaopuming/awesome-d could be 
integrated in the website, e.g. I've never heard of 
https://garden.dlang.io/ before!
Likewise, http://p0nce.github.io/d-idioms/ provide amazing tips. 
One (anecdotal) example is that `enum` is over-used in the docs 
while `static immutable` (with initializer) should arguably be 
the default for people.



 Feb 19 2020



  parent  Andrea Fontana <nospam example.com>  writes:


On Thursday, 20 February 2020 at 03:32:50 UTC, Mathias Lang wrote:

 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 [...]


 1. Dub documentation

 I agree.

 Some of this documentation will *also* require fixes to Dub 
 (e.g. https://github.com/dlang/dub/issues/1474 for anything 
 using preprocessor). There is a feature that allows a project 
 to provide skeleton for apps using it, it might also be useful 
 to try to do it with a few projects.

 2. DMD documentation

 I agree. Not only code documentation but also overview & c. 
 It's very difficult to help with dmd development starting from 
 nothing.



I would add a thing. Consider this:

bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (isInputRange!Range1 && isInputRange!Range2 && 
!isInfinite!Range1 && !isInfinite!Range2);

It's a pretty easy example of a function template. But I guess it 
is quite confusing for a newcomer. Why do we need to focus 
documentation on function signature? Can't we replace the 
function signature as main piece of information with something 
more easier to read for a newcomer?





Andrea



 Feb 20 2020



prev sibling next sibling parent  Kagamin <spam here.lot>  writes:


https://abload.de/img/tmpenki4.png - web 2.0 went too far.



 Feb 23 2020



prev sibling next sibling parent reply p.shkadzko <p.shkadzko gmail.com>  writes:


On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D ecosystem. 
 I can't provide any details yet because the details aren't yet 
 fixed. I don't even know for sure it's going to happen.

 However, the best way to make it happen is for us to have a 
 solid set of well-defined documentation tasks. Putting that 
 together is going to require help from the community. All of us 
 have encountered areas where improvement is needed in the spec, 
 the Phobos docs, and docs for dub, vibe.d, and many other tools 
 and projects around the D ecosystem. Some of it has made it 
 into Bugzilla (which will be mined for material), but much of 
 it has been buried in the forum archives or evaporated into the 
 ether from the IRC/Discord/Slack channels.

 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

 As I mention there, we need you to be as specific as you can. 
 What, specifically, is missing? What is unclear? What is 
 incorrect? Give as much detail as you can. We want to be able 
 to gather this info and define specific documentation tasks 
 that anyone can step in and complete with the information 
 provided.

 Any project in the D ecosystem is fair game. So please help us 
 out and tell us how D documentation can be improved for you.

 If you feel the urge to wax philosophical on something you see 
 here, please start a new thread and do all the philosophical 
 waxing you want there. Let's keep this one focused on listing 
 specific documentation issues. Do feel free to expand on any 
 post here with information you think is relevant.

 Thanks!


I would really like to see "Mir" library docs get more love: 
http://mir-algorithm.libmir.org

Being a D beginner and coming from Python world I struggle to 
understand why and how some examples work. I lack trivial 
information and for the most part the context. How is mir.ndslice 
`Slice` entity is different from D multidimensional array and why 
is it different in the first place. What is the big purpose and 
goal of the library documentation? When should we prefer it over 
traditional D arrays, etc. etc. This stuff belongs in the 
library. Right now mir docs are dry and incomplete which is a 
shame since it could grow into a serious Numpy alternative and 
bring more people into D.



 Mar 02 2020



  parent reply jmh530 <john.michael.hall gmail.com>  writes:


On Monday, 2 March 2020 at 14:13:16 UTC, p.shkadzko wrote:

 [snip]

 I would really like to see "Mir" library docs get more love: 
 http://mir-algorithm.libmir.org

 Being a D beginner and coming from Python world I struggle to 
 understand why and how some examples work. I lack trivial 
 information and for the most part the context. How is 
 mir.ndslice `Slice` entity is different from D multidimensional 
 array and why is it different in the first place. What is the 
 big purpose and goal of the library documentation? When should 
 we prefer it over traditional D arrays, etc. etc. This stuff 
 belongs in the library. Right now mir docs are dry and 
 incomplete which is a shame since it could grow into a serious 
 Numpy alternative and bring more people into D.


I agree that there could be some improvement here. I've intended 
to write something up, but haven't. There is a blog post from 
Shigeki Karita that is listed in the readme.md that I recall 
doing a decent job, but it is in Japanese and Google Translate 
doesn't seem to run on it anymore. I think there is an issue with 
the certificate or something. Probably just making a English 
version of it more easily available would be a step in the right 
direction.



 Mar 02 2020



  parent reply p.shkadzko <p.shkadzko gmail.com>  writes:


On Monday, 2 March 2020 at 16:55:36 UTC, jmh530 wrote:

 On Monday, 2 March 2020 at 14:13:16 UTC, p.shkadzko wrote:

 [...]


 I agree that there could be some improvement here. I've 
 intended to write something up, but haven't. There is a blog 
 post from Shigeki Karita that is listed in the readme.md that I 
 recall doing a decent job, but it is in Japanese and Google 
 Translate doesn't seem to run on it anymore. I think there is 
 an issue with the certificate or something. Probably just 
 making a English version of it more easily available would be a 
 step in the right direction.


I'd love to help and write some docs. Maybe something like a 
simplistic tutorial that Numpy has would already be great.



 Mar 03 2020



  parent  jmh530 <john.michael.hall gmail.com>  writes:


On Tuesday, 3 March 2020 at 15:30:40 UTC, p.shkadzko wrote:

 [snip]

 I'd love to help and write some docs. Maybe something like a 
 simplistic tutorial that Numpy has would already be great.


If you need someone to review it, I'd be happy to.



 Mar 03 2020



prev sibling next sibling parent  bachmeier <no spam.net>  writes:


On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:


 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):


We need documentation of strategies to optimize your code to get 
the best performance. There are numerous hacks that people 
suggest - look at this example

https://forum.dlang.org/post/ezomjijivexzrwtbtahn forum.dlang.org

but we should be able to link to a guide. Related to this, we 
need documentation on strategies to write programs without the GC.



 Mar 02 2020



prev sibling next sibling parent reply Panke <tobias pankrath.net>  writes:


On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D ecosystem. 
 I can't provide any details yet because the details aren't yet 
 fixed. I don't even know for sure it's going to happen.


Any news here?



 May 02 2020



  parent reply Mike Parker <aldacron gmail.com>  writes:


On Saturday, 2 May 2020 at 18:02:11 UTC, Panke wrote:

 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D 
 ecosystem. I can't provide any details yet because the details 
 aren't yet fixed. I don't even know for sure it's going to 
 happen.


 Any news here?


Not yet. It's going to happen at some point if we can sort out 
enough concrete documentation tasks.



 May 02 2020



  parent reply Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com>  writes:


On Sunday, 3 May 2020 at 01:37:54 UTC, Mike Parker wrote:

 Not yet. It's going to happen at some point if we can sort out 
 enough concrete documentation tasks.


Insight from a D newcomer for easier Dlang accessibility. Not 
everything is documentation per se:

- promote wiki.dlang.org directly on D's webpage

- promote authors to copy/write/(at least link) 
articles/tutorials/cookbooks on the wiki (there are many, but 
also many are scattered threw out the web)

- copy Dlang's blog to wiki (keep the blog, but collect 
information in one place. Plus points if directly sorted what the 
blog post was: article/tutorial/cookbook)

- declare unmaintained packages as such (once a month I read the 
question, whether derelict works, and once a month Mike answers, 
that he does not maintain it anymore. And this goes on for many 
packages. In addition it is hard to a newcomer to see, whether a 
package is abandoned, or finished. Example: coming from python 
word, anything which didn't have a commit in last 2 years is 
fishy)
( I don't want to attack you Mike, it is just an example, but 
since you are the one I am answering right now, it is the example)

- decrease score of packages, which don't build on code.dlang.org

- Language and library reference have enough examples (at least 
the parts I use). Examples are simple and clear. However to a 
newcomer needs also more complex examples, like tutorials or 
cookbooks. Idea: one link, on the specific reference to a section 
with related articles/tutorials/cookbooks.

- opinionated suggestions in getting started 
https://wiki.dlang.org/Getting_Started (a newcomer is overwhelmed 
by the possibilities of compilers,editors/ides. Suggestions: dmd, 
vscodium with code-d)

- probably pack this task list somewhere on the wiki

- Encourage newcomers to edit the wiki. This is a simple task, 
often dull to do for experienced community members, but great for 
newcomers, because they are included AND they explore the wiki 
ant the community on themselves.



 May 03 2020



  parent reply Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com>  writes:


On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:

 - Encourage newcomers to edit the wiki. This is a simple task, 
 often dull to do for experienced community members, but great 
 for newcomers, because they are included AND they explore the 
 wiki ant the community on themselves.


I felt encouraged today, so I created this list[1]
I hope it was OK.

Please feel free to fill, sort & enhance.


[1]: https://wiki.dlang.org/Documentation_improvement_initiative



 May 05 2020



  parent reply Mike Parker <aldacron gmail.com>  writes:


On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:

 On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:

 - Encourage newcomers to edit the wiki. This is a simple task, 
 often dull to do for experienced community members, but great 
 for newcomers, because they are included AND they explore the 
 wiki ant the community on themselves.


 I felt encouraged today, so I created this list[1]
 I hope it was OK.

 Please feel free to fill, sort & enhance.


 [1]: https://wiki.dlang.org/Documentation_improvement_initiative


Thanks!

I'm still looking for documentation tasks that require enough 
work that we can use them for the event. Adding one or two lines 
here or there isn't enough. And something that requires weeks is 
too much. We're looking for things that can be accomplished in 
terms of hours or days.



 May 05 2020



  parent reply WebFreak001 <d.forum webfreak.org>  writes:


On Wednesday, 6 May 2020 at 02:34:33 UTC, Mike Parker wrote:

 On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:

 On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:

 - Encourage newcomers to edit the wiki. This is a simple 
 task, often dull to do for experienced community members, but 
 great for newcomers, because they are included AND they 
 explore the wiki ant the community on themselves.


 I felt encouraged today, so I created this list[1]
 I hope it was OK.

 Please feel free to fill, sort & enhance.


 [1]: 
 https://wiki.dlang.org/Documentation_improvement_initiative


 Thanks!

 I'm still looking for documentation tasks that require enough 
 work that we can use them for the event. Adding one or two 
 lines here or there isn't enough. And something that requires 
 weeks is too much. We're looking for things that can be 
 accomplished in terms of hours or days.


How about also cleaning up documentation how it looks on the web? 
Like missing macros are rendered blank in ddox, so the usage or 
the definition could get fixed. Example missing something: 
https://vibed.org/api/vibe.db.mongo.mongo/ (ending with "a 
dedicated utility for this called .", missing the $(LINK2 ...) 
macro)

ddox also doesn't support showing mixin templates yet, which are 
however already reported in the JSON by the dmd documentation 
generator thing and only need some implementation.

Also something I'm finding essential and think should be added to 
the DDoc spec: $(LREF) and $(REF) - they are used a lot in phobos 
and (a bit biased) they are also implemented in the code-d doc 
preview / code tips already for all packages, making them look 
nicely already there. Even if it just suggests that these are 
subject to implementation for each documentation generator, 
having a well defined syntax and explanation would help a lot.



 May 05 2020



 next sibling parent  Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com>  writes:


On Wednesday, 6 May 2020 at 05:25:59 UTC, WebFreak001 wrote:

 How about also cleaning up documentation how it looks on the 
 web? Like missing macros are rendered blank in ddox, so the 
 usage or the definition could get fixed. Example missing 
 something: https://vibed.org/api/vibe.db.mongo.mongo/ (ending 
 with "a dedicated utility for this called .", missing the 
 $(LINK2 ...) macro)

 ddox also doesn't support showing mixin templates yet, which 
 are however already reported in the JSON by the dmd 
 documentation generator thing and only need some implementation.

 Also something I'm finding essential and think should be added 
 to the DDoc spec: $(LREF) and $(REF) - they are used a lot in 
 phobos and (a bit biased) they are also implemented in the 
 code-d doc preview / code tips already for all packages, making 
 them look nicely already there. Even if it just suggests that 
 these are subject to implementation for each documentation 
 generator, having a well defined syntax and explanation would 
 help a lot.


Please add it to the wiki.
https://wiki.dlang.org/Documentation_improvement_initiative#The_List



 May 06 2020



prev sibling  parent reply David Gileadi <gileadisNOSPM gmail.com>  writes:


On 5/5/20 10:25 PM, WebFreak001 wrote:

 On Wednesday, 6 May 2020 at 02:34:33 UTC, Mike Parker wrote:

 On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:

 On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:

 - Encourage newcomers to edit the wiki. This is a simple task, often 
 dull to do for experienced community members, but great for 
 newcomers, because they are included AND they explore the wiki ant 
 the community on themselves.


 I felt encouraged today, so I created this list[1]
 I hope it was OK.

 Please feel free to fill, sort & enhance.


 [1]: https://wiki.dlang.org/Documentation_improvement_initiative


 Thanks!

 I'm still looking for documentation tasks that require enough work 
 that we can use them for the event. Adding one or two lines here or 
 there isn't enough. And something that requires weeks is too much. 
 We're looking for things that can be accomplished in terms of hours or 
 days.


 
 How about also cleaning up documentation how it looks on the web? Like 
 missing macros are rendered blank in ddox, so the usage or the 
 definition could get fixed. Example missing something: 
 https://vibed.org/api/vibe.db.mongo.mongo/ (ending with "a dedicated 
 utility for this called .", missing the $(LINK2 ...) macro)
 
 ddox also doesn't support showing mixin templates yet, which are however 
 already reported in the JSON by the dmd documentation generator thing 
 and only need some implementation.
 
 Also something I'm finding essential and think should be added to the 
 DDoc spec: $(LREF) and $(REF) - they are used a lot in phobos and (a bit 
 biased) they are also implemented in the code-d doc preview / code tips 
 already for all packages, making them look nicely already there. Even if 
 it just suggests that these are subject to implementation for each 
 documentation generator, having a well defined syntax and explanation 
 would help a lot.


Incidentally in my -preview=markdown changes putting a symbol in 
brackets (using Markdown syntax for a link) like [string] creates a link 
to that symbol's definition [1]. I suspect my implementation isn't 
perfect, but like the rest of the -preview=markdown changes my hope is 
that it makes the docs easier to write.

[1]: https://dlang.org/spec/ddoc.html#reference_links



 May 06 2020



  parent  Adam D. Ruppe <destructionator gmail.com>  writes:


On Wednesday, 6 May 2020 at 14:24:53 UTC, David Gileadi wrote:

 Incidentally in my -preview=markdown changes putting a symbol 
 in brackets (using Markdown syntax for a link) like [string] 
 creates a link to that symbol's definition


Yeah, my adrdox does something similar. 
http://dpldocs.info/experimental-docs/adrdox.syntax.html#cross-referencing

I also rewrite REF and LREF into it for phobos compatibility 
internally but it is a pretty obvious win to define these.

(actually adrdox defines EVERYTHING and doesn't allow 
user-defined macros at all. Standardization makes it easier to 
use here. I just hard-coded the supported ones and leave the rest 
the unmodified.)



 May 06 2020



prev sibling  parent reply Guillaume Piolat <first.last gmail.com>  writes:


On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D ecosystem. 
 I can't provide any details yet because the details aren't yet 
 fixed. I don't even know for sure it's going to happen.

 However, the best way to make it happen is for us to have a 
 solid set of well-defined documentation tasks. Putting that 
 together is going to require help from the community. All of us 
 have encountered areas where improvement is needed in the spec, 
 the Phobos docs, and docs for dub, vibe.d, and many other tools 
 and projects around the D ecosystem. Some of it has made it 
 into Bugzilla (which will be mined for material), but much of 
 it has been buried in the forum archives or evaporated into the 
 ether from the IRC/Discord/Slack channels.

 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

 As I mention there, we need you to be as specific as you can. 
 What, specifically, is missing? What is unclear? What is 
 incorrect? Give as much detail as you can. We want to be able 
 to gather this info and define specific documentation tasks 
 that anyone can step in and complete with the information 
 provided.

 Any project in the D ecosystem is fair game. So please help us 
 out and tell us how D documentation can be improved for you.


Recently I spent more than 15 minutes trying to **get the Date of 
today** with std.datetime.


The answer is:


     import std.datetime;
     Date today()
     {
         SysTime time = Clock.currTime();
         return Date(time.year, time.month, time.day);
     }

to do it you need to know what a SysTime is, what Clock is.

It's the kind of examples that would really improve life for the 
stdlib user, with simple copy-pasting often being enough.


Another one I'm using constantly is:


    /// Returns: Most precise clock ticks, in microseconds.
    long getTickUs() nothrow  nogc
    {
       import core.time;
       return convClockFreq(MonoTime.currTime.ticks, 
MonoTime.ticksPerSecond, 1_000_000);
    }

**It's not trivial at all either!**
I think small example for common tasks like can bring back some 
productivity.



On the contrary, `read` the most useful function of `std.file`, 
has an example: https://dlang.org/phobos/std_file.html#.read



 May 08 2020



 next sibling parent  Steven Schveighoffer <schveiguy gmail.com>  writes:


On 5/8/20 11:34 AM, Guillaume Piolat wrote:

 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 Preliminary discussions are underway for a new event to encourage 
 improvements to documentation across the D ecosystem. I can't provide 
 any details yet because the details aren't yet fixed. I don't even 
 know for sure it's going to happen.

 However, the best way to make it happen is for us to have a solid set 
 of well-defined documentation tasks. Putting that together is going to 
 require help from the community. All of us have encountered areas 
 where improvement is needed in the spec, the Phobos docs, and docs for 
 dub, vibe.d, and many other tools and projects around the D ecosystem. 
 Some of it has made it into Bugzilla (which will be mined for 
 material), but much of it has been buried in the forum archives or 
 evaporated into the ether from the IRC/Discord/Slack channels.

 This thread is a place to collect your documentation pain in one 
 place. I'm about to publish a blog post announcing this (a few minutes 
 after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

 As I mention there, we need you to be as specific as you can. What, 
 specifically, is missing? What is unclear? What is incorrect? Give as 
 much detail as you can. We want to be able to gather this info and 
 define specific documentation tasks that anyone can step in and 
 complete with the information provided.

 Any project in the D ecosystem is fair game. So please help us out and 
 tell us how D documentation can be improved for you.


 
 Recently I spent more than 15 minutes trying to **get the Date of 
 today** with std.datetime.
 
 
 The answer is:
 
 
      import std.datetime;
      Date today()
      {
          SysTime time = Clock.currTime();
          return Date(time.year, time.month, time.day);
      }
 
 to do it you need to know what a SysTime is, what Clock is.


You can do:
return cast(Date)Clock.currTime;

Though I have never liked the requirement to cast. There really should 
just be a Date.currDate or SysTime.date accessor.


 
 Another one I'm using constantly is:
 
 
     /// Returns: Most precise clock ticks, in microseconds.
     long getTickUs() nothrow  nogc
     {
        import core.time;
        return convClockFreq(MonoTime.currTime.ticks, 
 MonoTime.ticksPerSecond, 1_000_000);
     }
 
 **It's not trivial at all either!**
 I think small example for common tasks like can bring back some 
 productivity.


This one is easier:

(MonoTime.currTime - MonoTime.zero).total!"usecs";

-Steve



 May 08 2020



prev sibling  parent reply jmh530 <john.michael.hall gmail.com>  writes:


On Friday, 8 May 2020 at 15:34:43 UTC, Guillaume Piolat wrote:

 [snip]

 Recently I spent more than 15 minutes trying to **get the Date 
 of today** with std.datetime.


 The answer is:


     import std.datetime;
     Date today()
     {
         SysTime time = Clock.currTime();
         return Date(time.year, time.month, time.day);
     }
 [snip]


I think this should be in phobos, regardless of the documentation 
improvement.



 May 08 2020



  parent  Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com>  writes:


Today I was very satisfied with the dub documentation.

However I don't know if anyone has actually done anything, or 
duckduckgo just actually finds it now.

(More specifically this: https://dub.pm/package-format-json.html)

So either I was too stupid to properly search half a year a ago, 
or someone did a tremendous job meanwhile (which I missed).

I updated 
https://wiki.dlang.org/Documentation_improvement_initiative



 Jun 25 2020