On Friday, 18 December 2015 at 07:37:40 UTC, Jacob Carlborg wrote:
> On 2015-12-18 00:50, Andrei Alexandrescu wrote:
>
>> * Many functions don't have "Parameters:", "Returns:", or "Throws:"
>> sections. Those that respectively take parameters, return non-void, or
>> throw, should have one each.
>
> I think we need to be better at enforcing this in the pull requests. I see a lot of this [2] in PR's.

After further changes I was able to add `Params:` and `Returns:` with some valuable information, but it also comes with a fair amount of redundancy. I think a lot of our current functions have more than adequately documented parameters and return values, just without using sections. Some redundancy can be a good thing, but for most of those functions I don't see how simple-mindedly adding purely redundant information is impactful.

The important thing is not those sections but that parameters and return values are documented.

On 2015-12-19 06:01, Jakob Ovrum wrote:

> After further changes I was able to add `Params:` and `Returns:` with
> some valuable information, but it also comes with a fair amount of
> redundancy.

Ok, cool. I missed that.

-- 
/Jacob Carlborg

On 2015-12-18 12:07, Walter Bright wrote:

> I did have a look. Most of the PR is code and content, not markup. And
> most of the markup that is there is straightforward, like marking pages
> with $(P ... ).

I'm talking about the comments in the PR, not the contents of the PR. It shows that the problems I had was with Ddoc and styling, not the content.

-- 
/Jacob Carlborg

On 2015-12-18 14:15, Andrei Alexandrescu wrote:

> As I said: a growing number of people able and willing to maintain and
> improve it. -- Andrei

I'm not sure if there's some miscommunications here.

But more contributors will not magically help. There most be a reason for why Ddox is not the default documentation. Some features that are missing, some parts that are not good enough or similar. There needs to be a list of criteria for when Ddox can be made default. The contributors can work on these tasks that will improve Ddox which will eventually lead to making Ddox default.

I'm asking for specifics. If nobody has the answer for this we don't know why Ddox is not good enough. And if we don't know that we can't really know that it's not good enough. And if that's the case it could be made the default right now.

-- 
/Jacob Carlborg

On 12/19/15 12:01 AM, Jakob Ovrum wrote:
>
> After further changes I was able to add `Params:` and `Returns:` with
> some valuable information, but it also comes with a fair amount of
> redundancy. I think a lot of our current functions have more than
> adequately documented parameters and return values, just without using
> sections. Some redundancy can be a good thing, but for most of those
> functions I don't see how simple-mindedly adding purely redundant
> information is impactful.
>
> The important thing is not those sections but that parameters and return
> values are documented.

Agreed there's got to be measure in everything. I'm thinking in those cases the existing documentation should be reformatted with the standard sections.

When you do standard-formatted documentation for many functions at once, it seems kinda trite. But for folks who work on some program and want to look up one function, reliance on a standard uniform format is very helpful.


Andrei

On Sat, Dec 19, 2015 at 09:58:44AM -0500, Andrei Alexandrescu via Digitalmars-d wrote:
> On 12/19/15 12:01 AM, Jakob Ovrum wrote:
> >After further changes I was able to add `Params:` and `Returns:` with some valuable information, but it also comes with a fair amount of redundancy. I think a lot of our current functions have more than adequately documented parameters and return values, just without using sections. Some redundancy can be a good thing, but for most of those functions I don't see how simple-mindedly adding purely redundant information is impactful.
> >
> >The important thing is not those sections but that parameters and return values are documented.
> 
> Agreed there's got to be measure in everything. I'm thinking in those cases the existing documentation should be reformatted with the standard sections.
> 
> When you do standard-formatted documentation for many functions at once, it seems kinda trite. But for folks who work on some program and want to look up one function, reliance on a standard uniform format is very helpful.
[...]

Yes, Walter has said the same thing before. Where the description is too short to warrant being in both a standard section and in prose, put it in the standard section. I'd even propose that it's OK to leave the function description blank if the info in the standard Params: and Returns: sections already fully define what it does.  This isn't as literary, but we're writing reference documentation, not an essay contest, and consistently having information in standard sections makes it more useful as a reference.


T

-- 
"Hi." "'Lo."

On Saturday, 19 December 2015 at 10:54:36 UTC, Jacob Carlborg wrote:
> On 2015-12-18 14:15, Andrei Alexandrescu wrote:
>
>> As I said: a growing number of people able and willing to maintain and
>> improve it. -- Andrei
>
> I'm not sure if there's some miscommunications here.
>
> But more contributors will not magically help. There most be a reason for why Ddox is not the default documentation. Some features that are missing, some parts that are not good enough or similar. There needs to be a list of criteria for when Ddox can be made default. The contributors can work on these tasks that will improve Ddox which will eventually lead to making Ddox default.
>
> I'm asking for specifics. If nobody has the answer for this we don't know why Ddox is not good enough. And if we don't know that we can't really know that it's not good enough. And if that's the case it could be made the default right now.

There is no definitive answer for when something is "good enough", but to get you started:

https://github.com/rejectedsoftware/ddox/issues

Note that many of these are essentially DMD JSON output bugs/limitations.

On 2015-12-21 04:44, Vladimir Panteleev wrote:

> There is no definitive answer for when something is "good enough"

If nobody knows what it takes to make Ddox the default, how do we know that it's not already good enough?

> but to get you started:
>
> https://github.com/rejectedsoftware/ddox/issues

Finally :)

-- 
/Jacob Carlborg

On Thursday, 17 December 2015 at 13:44:31 UTC, John Colvin wrote:
> On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright wrote:
>> On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote:
>>> Having said that, though, using ddoc for the website leads to other
>>> problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the
>>> associated relative/absolute URL nightmare that a proper web authoring
>>> system would have taken care of by default).
>>
>> Annoying, and maybe you have to spend a couple minutes picking the right one if you've forgotten for the moment => absolute nightmare? Come on.
>
> How does a user who happens to spot a mistake in the docs and wants to help work this out?

This is happening to me right now.
I have a live editor open in github to edit the template doc page. I'm trying to link to std.traits and cannot find how. FULL_XREF is used on the same page, but I don't know what arguments it can accept.