Add ddoc style comments to all diagnostic functions. by ibuclaw · Pull Request #7812 · dlang/dmd

ibuclaw · 2018-01-30T23:40:03Z

Mostly mechanical / repetitive comments.

dlang-bot · 2018-01-30T23:40:04Z

Thanks for your pull request, @ibuclaw!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

wilzbach · 2018-01-30T23:46:19Z

src/dmd/errors.d

+ * Params:
+ *      loc = location of error
+ *      format = printf-style format specification
+ */


Not that I would care much about (and it makes sense in DMD's ugly codebase), but as an FYI we recently defined documentation strings in the DStyle.

wilzbach · 2018-01-30T23:46:59Z

src/dmd/errors.d


-// header is "Error: " by default (see errors.h)
+/**
+ * Same as $(D error), but takes a va_list parameter, and optionally additional message prefixes.


FYI: Phobos is slowly converted to use backticks instead of $(D ...)

Would you prefer that changed?

It was just an FYI. I have given up hope for a pretty DMD codebase long ago.

wilzbach

Doc improvements are always welcome!

JinShil · 2018-01-30T23:57:24Z

Per https://dlang.org/dstyle.html#phobos_documentation

Documentation comments should not have leading stars or zeroes on each line.

But I don't think that should hold up this PR.

wilzbach · 2018-01-31T00:49:25Z

But I don't think that should hold up this PR.

Yes, it was just an FYI as it was added four days ago and I assume it's not very known: dlang/dlang.org#2129

Anyhow the DDoc failures are a holdup:

dmd/errors.d(41): Warning: Ddoc: parameter count mismatch
dmd/errors.d(55): Warning: Ddoc: parameter count mismatch
dmd/errors.d(71): Warning: Ddoc: parameter count mismatch
dmd/errors.d(90): Warning: Ddoc: parameter count mismatch
dmd/errors.d(104): Warning: Ddoc: parameter count mismatch
dmd/errors.d(120): Warning: Ddoc: parameter count mismatch
dmd/errors.d(120): Warning: Ddoc: parameter count mismatch
dmd/errors.d(135): Warning: Ddoc: parameter count mismatch
dmd/errors.d(150): Warning: Ddoc: parameter count mismatch

ibuclaw · 2018-01-31T00:55:11Z

Anyhow the DDoc failures are a holdup:

I did have a quick look in phobos/druntime, and I couldn't see any existing documentation for ellipses.

Blindly trying ...

ibuclaw · 2018-01-31T01:28:16Z

I'm not convinced that adding a documented ... parameter works.

http://dtest.dlang.io/artifact/website-4add4e35db29d29eacfafcc97d5b06f9455e1982-10dea7bc7624f4925e8c3df676e15966/web/library-prerelease/dmd/errors/message.html

JinShil · 2018-01-31T06:56:07Z

I restarted Jenkins

jacob-carlborg · 2018-01-31T06:57:47Z

src/dmd/errors.d

+ * Print additional details about a warning message.
+ * Doesn't increase the error count or print an additional warning prefix.
+ * Params:
+ * Params:


Double params.

WalterBright · 2018-01-31T07:46:26Z

src/dmd/errors.d

 }

+/**
+ * Print additional details about an error mesage.


ibuclaw · 2018-01-31T07:52:37Z

@WalterBright - I ran the source through aspell and picked up a couple of other spelling mistakes.

ibuclaw · 2018-01-31T08:21:13Z

Yep, although the compiler complains if ... is missing, it doesn't do a good job formatting it.

http://dtest.dlang.io/artifact/website-6a94b9083d4ac94d03bfb3506e1cabbbfd3df19e-a80c86ba9803958733cdbcefd4eca848/web/library-prerelease/dmd/errors/deprecation.html

Or recognising it.

http://dtest.dlang.io/artifact/website-6a94b9083d4ac94d03bfb3506e1cabbbfd3df19e-a80c86ba9803958733cdbcefd4eca848/web/library-prerelease/dmd/errors.html

jacob-carlborg · 2018-01-31T08:22:34Z

src/dmd/errors.d

+/**
 * Embed these highlighting commands in the text stream.
- * HIGHLIGHT.Escape indicats a Color follows.
+ * HIGHLIGHT.Escape indicates a Color follows.


Backticks around HIGHLIGHT.Escape.

WalterBright · 2018-01-31T09:05:28Z

src/dmd/errors.d

 import dmd.root.rmem;
 import dmd.console;

-/**********************


It's not really necessary to do this. The number of *'s is not consistent anywhere in the source code, and it hardly matters.

ibuclaw · 2018-02-01T08:04:08Z

Yep, although the compiler complains if ...is missing, it doesn't do a good job formatting it.

Ah I've just realised that this is a ddox bug. The ddoc page is fine. :-)

ibuclaw added the Review:Easy Review label Jan 30, 2018

ibuclaw force-pushed the ddocerrors branch from a56b62a to be5b590 Compare January 30, 2018 23:44

wilzbach reviewed Jan 30, 2018

View reviewed changes

wilzbach approved these changes Jan 30, 2018

View reviewed changes

ibuclaw force-pushed the ddocerrors branch from be5b590 to e73179d Compare January 30, 2018 23:47

JinShil approved these changes Jan 30, 2018

View reviewed changes

ibuclaw force-pushed the ddocerrors branch from e73179d to 7658782 Compare January 31, 2018 01:07

jacob-carlborg suggested changes Jan 31, 2018

View reviewed changes

ibuclaw force-pushed the ddocerrors branch from 7658782 to d40d344 Compare January 31, 2018 07:41

WalterBright reviewed Jan 31, 2018

View reviewed changes

src/dmd/errors.d Outdated

}

/**

* Print additional details about an error mesage.

Copy link

Member

WalterBright Jan 31, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

message

ibuclaw force-pushed the ddocerrors branch from d40d344 to b914da4 Compare January 31, 2018 07:47

WalterBright added the Merge:auto-merge label Jan 31, 2018

Add ddoc style comments to all diagnostic functions.

83fb059

ibuclaw force-pushed the ddocerrors branch from b914da4 to 83fb059 Compare January 31, 2018 07:52

dlang-bot removed the Merge:auto-merge label Jan 31, 2018

jacob-carlborg reviewed Jan 31, 2018

View reviewed changes

jacob-carlborg approved these changes Jan 31, 2018

View reviewed changes

WalterBright reviewed Jan 31, 2018

View reviewed changes

wilzbach added the Merge:auto-merge label Jan 31, 2018

dlang-bot merged commit b879b1f into dlang:master Jan 31, 2018

ibuclaw deleted the ddocerrors branch January 31, 2018 13:47

Uh oh!

Conversation

ibuclaw commented Jan 30, 2018

Uh oh!

dlang-bot commented Jan 30, 2018

Bugzilla references

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wilzbach left a comment

Choose a reason for hiding this comment

Uh oh!

JinShil commented Jan 30, 2018

Uh oh!

wilzbach commented Jan 31, 2018

Uh oh!

ibuclaw commented Jan 31, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ibuclaw commented Jan 31, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JinShil commented Jan 31, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ibuclaw commented Jan 31, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ibuclaw commented Jan 31, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ibuclaw commented Feb 1, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ibuclaw commented Jan 31, 2018 •

edited

Loading

ibuclaw commented Jan 31, 2018 •

edited

Loading

ibuclaw commented Jan 31, 2018 •

edited

Loading