Bug 16992 – ddoc does not match documented unittest with static template method

In std.datetime, there are no examples for fromISOString, fromISOExtString, and fromSimpleString. The examples need to make it clear how to properly call those functions. Initially I followed the natural approach import std.datetime, std.stdio; void main() { writeln(fromISOString("20161208T032055")); } but it would not compile. Digging around, I found that it needs to be writeln(DateTime.fromISOString("20161208T032055"));

Well, that's odd, as all of these functions have ddoc-ed unit tests below them, but they aren't showing in the docs for some reason.

It seems that the documentation builder has a problem with static methods. After erasing the static keyword from one method, the documentation appeared as usual. From what I've seen in phobos, static methods usually do no have examples.

The examples to appear in ddox, see e.g. https://dlang.org/library/std/datetime/date.from_iso_string.html. The problem is therefore in ddmd/src/doc.d. Probably the intent was to not generate examples for module-level static functions because those are not accessible publicly anyway.

s/to appear/do appear/

For now we could wrap the static call in a public call outside the struct and generate documentation for that function (and other overloads).

(In reply to RazvanN from comment #5) > For now we could wrap the static call in a public call outside the struct > and generate documentation for that function (and other overloads). Why not fix the compiler?

I think that having all fromISOString overloads gathered in a single template function which is called fromISOString!Choose_type(some_string), where Choose_type is one of {Date, DateTime, TimeOfDay} is more elegant and the documentation can be presented a single time; rather than having 3 fromISOString functions dispersed through the documentation.

(In reply to RazvanN from comment #7) > I think that having all fromISOString overloads gathered in a single > template function which is called fromISOString!Choose_type(some_string), > where Choose_type is one of {Date, DateTime, TimeOfDay} is more elegant and > the documentation can be presented a single time; rather than having 3 > fromISOString functions dispersed through the documentation. They're dispersed, because they go with each individual type and are specific to each individual type. They have distinct implemnetations and should be documented as such. I see no reason to have a module-level wrapper function - especially when not all of the time point types are even in the same module anymore, now that std.datetime has been split up. The issue here is that the documentation examples do not show up in the ddoc-generated documentation in spite of the fact that they are in the code as ddoc-ed examples. There is no need to change std.datetime here. We need to fix the compiler.

FYI: We already have a pipeline to test for public unittests. Try ``` make -f posix.mak std/datetime/date.publictests ``` That one is based on libdparse. https://github.com/dlang/tools/blob/master/tests_extractor.d Anyhow, the compiler must be fixed!

(In reply to RazvanN from comment #2) > It seems that the documentation builder has a problem with static methods. > After erasing the static keyword from one method, the documentation appeared > as usual. It only happens when the method is a template. Reduced test case: struct Date { /// static void fromISOString()() {} /// unittest { // hi } }

Also note that `static` is missing from the template methods: https://dlang.org/phobos/std_datetime_date.html#.Date.fromISOString If you remove the template parentheses, `static` reappears.

THIS ISSUE HAS BEEN MOVED TO GITHUB https://github.com/dlang/dmd/issues/19218 DO NOT COMMENT HERE ANYMORE, NOBODY WILL SEE IT, THIS ISSUE HAS BEEN MOVED TO GITHUB