On Tue, Sep 3, 2019 at 7:30 AM jmh530 via Digitalmars-d-announce <digitalmars-d-announce@puremagic.com> wrote:
>
> On Tuesday, 3 September 2019 at 14:02:43 UTC, bachmeier wrote:
> > [snip]
> >
> > Those are a big deal. From a marketing perspective, those are gold IMO.
>
> If these are as big a deal as people seem to think, the documentation could be improved by including a brief example of how to use.
>
> In addition, the documentation page for vector [1] seems a bit thin. It doesn't have the top-level comment like basic_string does [2]. At a minimum, that should be fixed before going on a marketing blitz...
>
> [1] https://dlang.org/phobos/core_stdcpp_vector.html
> [2]
> https://github.com/dlang/druntime/blob/f07859b9b33740d7d7357ca3e27077f91c02dfc8/src/core/stdcpp/string.d#L59

Interesting... you can see in the code, there are doco comments
everywhere, but the docs are empty O_o
Also the second line of the description linking to the C++ docs is
missing too... where did all the docs go?

I've tried to iterate on the docs a couple of times, but I have no
idea how I'm supposed to do it, because they're only published when
the PR is merged... how are you supposed to iterate locally?
That empty doco is not what I expect from looking at the source.

But yeah, I agree. More will come online soon-ish. We can give one release to harden them up a bit before making a fuss about it.

On 9/3/2019 1:22 AM, Manu wrote:
> Huzzah!
> 
> I like to think std::string and std::vector are a pretty big deal too ;)
> 

They are. Congrats!

On Thursday, 5 September 2019 at 20:55:15 UTC, Manu wrote:
> [snip]
>
> Interesting... you can see in the code, there are doco comments
> everywhere, but the docs are empty O_o
> Also the second line of the description linking to the C++ docs is
> missing too... where did all the docs go?
>

The point I was trying to make wrt basic_string was that the top of it looks like

/**
 * D language counterpart to C++ std::basic_string.
 *
 * C++ reference: $(LINK2 https://en.cppreference.com/w/cpp/string/basic_string)
 */
extern(C++, class)
extern(C++, (StringNamespace))
struct basic_string(T, Traits = char_traits!T, Alloc = allocator!T)

whereas the top of vector looks like

extern(C++, class) struct vector(T, Alloc = allocator!T)

It has no top-level comment. With no top-level comment, all the other documentation won't show up.

On Fri, Sep 6, 2019 at 3:50 AM jmh530 via Digitalmars-d-announce <digitalmars-d-announce@puremagic.com> wrote:
>
> On Thursday, 5 September 2019 at 20:55:15 UTC, Manu wrote:
> > [snip]
> >
> > Interesting... you can see in the code, there are doco comments
> > everywhere, but the docs are empty O_o
> > Also the second line of the description linking to the C++ docs
> > is
> > missing too... where did all the docs go?
> >
>
> The point I was trying to make wrt basic_string was that the top of it looks like
>
> /**
>   * D language counterpart to C++ std::basic_string.
>   *
>   * C++ reference: $(LINK2
> https://en.cppreference.com/w/cpp/string/basic_string)
>   */
> extern(C++, class)
> extern(C++, (StringNamespace))
> struct basic_string(T, Traits = char_traits!T, Alloc =
> allocator!T)
>
> whereas the top of vector looks like
>
> extern(C++, class) struct vector(T, Alloc = allocator!T)
>
> It has no top-level comment. With no top-level comment, all the other documentation won't show up.

I'll give it a good do-over.

What's the story with string though; the second line (linking back to the C++ reference) of the doco isn't there... O_o

On Saturday, 7 September 2019 at 07:16:36 UTC, Manu wrote:
> [snip]
>
> What's the story with string though; the second line (linking back to the C++ reference) of the doco isn't there... O_o

Hmm, I didn't notice that. It also is a problem for core.stdcpp.array. I'm looking at other uses of LINK2 in druntime and they are usually of the form $(LINK2 http:/xxx, some_text). Without digging in to the documentation generator, I think LINK2 is meant to be used when you want to replace the link with some text. I don't see many cases of raw links being used (the source shows up as a raw link, but it's not done that way in the files), someone else may know better than I do.

On Sat, Sep 7, 2019 at 9:05 AM jmh530 via Digitalmars-d-announce <digitalmars-d-announce@puremagic.com> wrote:
>
> On Saturday, 7 September 2019 at 07:16:36 UTC, Manu wrote:
> > [snip]
> >
> > What's the story with string though; the second line (linking back to the C++ reference) of the doco isn't there... O_o
>
> Hmm, I didn't notice that. It also is a problem for core.stdcpp.array. I'm looking at other uses of LINK2 in druntime and they are usually of the form $(LINK2 http:/xxx, some_text). Without digging in to the documentation generator, I think LINK2 is meant to be used when you want to replace the link with some text. I don't see many cases of raw links being used (the source shows up as a raw link, but it's not done that way in the files), someone else may know better than I do.

The text before the link is gone too.
I don't know how to iterate on the docs, since they only appear from
CI, and I have no idea how to create them myself :/

On 9/7/19 12:27 PM, Manu wrote:
> I don't know how to iterate on the docs, since they only appear from
> CI, and I have no idea how to create them myself :/

I don't know what the "correct" way is, but to build dlang.org locally on macOS, from the dlang.org dir I run:

    DIFFABLE=1 make -f posix.mak html

To build phobos docs locally, from the phobos dir I run:

    make -f posix.mak build-html

To build druntime locally, from the druntime dir I run:

    make -f posix.mak doc

However this last one fails for me on macOS due to platform-specific compile errors:

    src/core/stdcpp/typeinfo.d(147): Error: static assert:  "Missing std::type_info binding for this platform"

In any case you'll find all the generated local docs in your dlang.org/web dir.