False Positive for no public example

[JackStouffer]

std.conv line 4179

/***************************************************************
 * Convenience functions for converting one or more arguments
 * of any type into _text (the three character widths).
 */
string text(T...)(T args)
if (T.length > 0) { return textImpl!string(args); }

// @@@DEPRECATED_2018-06@@@
deprecated("Calling `text` with 0 arguments is deprecated")
string text(T...)(T args)
if (T.length == 0) { return textImpl!string(args); }

///ditto
wstring wtext(T...)(T args)
if (T.length > 0) { return textImpl!wstring(args); }

// @@@DEPRECATED_2018-06@@@
deprecated("Calling `wtext` with 0 arguments is deprecated")
wstring wtext(T...)(T args)
if (T.length == 0) { return textImpl!wstring(args); }

///ditto
dstring dtext(T...)(T args)
if (T.length > 0) { return textImpl!dstring(args); }

///
@safe unittest
{
    assert( text(42, ' ', 1.5, ": xyz") == "42 1.5: xyz"c);
    assert(wtext(42, ' ', 1.5, ": xyz") == "42 1.5: xyz"w);
    assert(dtext(42, ' ', 1.5, ": xyz") == "42 1.5: xyz"d);
}

yields

std/conv.d(4179:8)[warn]: Public declaration 'text' has no documented example.

[wilzbach]

I just has a look into this and the check previously did ignore private symbols, but was changed due to https://github.com/dlang-community/D-Scanner/issues/500.

The problem is that ddoc isn't smart enough to detect this:

///
void dirName(C)(C[] path) {}

private void _dirName(R)(R path){}

/// <- not part of the docs
@safe unittest
{
    ...
}

https://docarchives.dlang.io/v2.079.0/phobos/std_path.html#dirName https://docarchives.dlang.io/v2.079.0/library/std/path/dir_name.html

In the PRs you referenced this issue, it's the problem of private symbols being between the public symbol and the public unittests. I assume it's a similar behavior for non-documented deprecated symbols.

Interestingly, when trying this with Ddoc, I noticed the following

This works:

/// Foo
auto text(T...)(T args)
if (T.length > 0) {}

private auto text(T...)(T args)
if (T.length == 0) {}

///ditto
auto wtext(T...)(T args)
if (T.length > 0) {}

///
@safe unittest
{
    assert(1 == 1);
}

https://run.dlang.io/is/7WoWQE

whereas this doesn't work:

/// Foo
auto text(T...)(T args)
if (T.length > 0) {}

private auto text(T...)(T args)
if (T.length == 0) {}

///
@safe unittest
{
    assert(1 == 1);
}

https://run.dlang.io/is/QWNx9O

So we could now add this weird DDoc logic into Dscanner, but I guess it's better to simply fix Ddoc.

[Hackerpilot]

So we could now add this weird DDoc logic into Dscanner, but I guess it's better to simply fix Ddoc.

And hopefully also update the ddoc specification to say what should happen.