Skip to content

Add ddoc style comments to all diagnostic functions. #7812

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dlang-bot merged 1 commit into from
Jan 31, 2018
Merged

Add ddoc style comments to all diagnostic functions. #7812

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 124 additions & 21 deletions src/dmd/errors.d
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import dmd.root.outbuffer;
import dmd.root.rmem;
import dmd.console;

/**********************
Copy link
Copy Markdown
Member

@WalterBright WalterBright Jan 31, 2018

Choose a reason for hiding this comment

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

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

/**
* Color highlighting to classify messages
*/
enum Classification
Expand All @@ -32,8 +32,12 @@ enum Classification
deprecation = Color.brightCyan, /// for deprecations
}

/**************************************
* Print error message
/**
* Print an error message, increasing the global error count.
* Params:
* loc = location of error
* format = printf-style format specification
* ... = printf-style variadic arguments
*/
extern (C++) void error(const ref Loc loc, const(char)* format, ...)
{
Expand All @@ -43,7 +47,13 @@ extern (C++) void error(const ref Loc loc, const(char)* format, ...)
va_end(ap);
}

// This override allows Loc() literals to be passed.
/**
* Same as above, but allows Loc() literals to be passed.
* Params:
* loc = location of error
* format = printf-style format specification
* ... = printf-style variadic arguments
*/
extern (D) void error(Loc loc, const(char)* format, ...)
{
va_list ap;
Expand All @@ -52,6 +62,15 @@ extern (D) void error(Loc loc, const(char)* format, ...)
va_end(ap);
}

/**
* Same as above, but takes a filename and line information arguments as separate parameters.
* Params:
* filename = source file of error
* linnum = line in the source file
* charnum = column number on the line
* format = printf-style format specification
* ... = printf-style variadic arguments
*/
extern (C++) void error(const(char)* filename, uint linnum, uint charnum, const(char)* format, ...)
{
Loc loc;
Expand All @@ -64,6 +83,14 @@ extern (C++) void error(const(char)* filename, uint linnum, uint charnum, const(
va_end(ap);
}

/**
* Print additional details about an error message.
* Doesn't increase the error count or print an additional error prefix.
* Params:
* loc = location of error
* format = printf-style format specification
* ... = printf-style variadic arguments
*/
extern (C++) void errorSupplemental(const ref Loc loc, const(char)* format, ...)
{
va_list ap;
Expand All @@ -72,6 +99,13 @@ extern (C++) void errorSupplemental(const ref Loc loc, const(char)* format, ...)
va_end(ap);
}

/**
* Print a warning message, increasing the global warning count.
* Params:
* loc = location of warning
* format = printf-style format specification
* ... = printf-style variadic arguments
*/
extern (C++) void warning(const ref Loc loc, const(char)* format, ...)
{
va_list ap;
Expand All @@ -80,6 +114,14 @@ extern (C++) void warning(const ref Loc loc, const(char)* format, ...)
va_end(ap);
}

/**
* Print additional details about a warning message.
* Doesn't increase the warning count or print an additional warning prefix.
* Params:
* loc = location of warning
* format = printf-style format specification
* ... = printf-style variadic arguments
*/
extern (C++) void warningSupplemental(const ref Loc loc, const(char)* format, ...)
{
va_list ap;
Expand All @@ -88,6 +130,14 @@ extern (C++) void warningSupplemental(const ref Loc loc, const(char)* format, ..
va_end(ap);
}

/**
* Print a deprecation message, may increase the global warning or error count
* depending on whether deprecations are ignored.
* Params:
* loc = location of deprecation
* format = printf-style format specification
* ... = printf-style variadic arguments
*/
extern (C++) void deprecation(const ref Loc loc, const(char)* format, ...)
{
va_list ap;
Expand All @@ -96,6 +146,14 @@ extern (C++) void deprecation(const ref Loc loc, const(char)* format, ...)
va_end(ap);
}

/**
* Print additional details about a deprecation message.
* Doesn't increase the error count, or print an additional deprecation prefix.
* Params:
* loc = location of deprecation
* format = printf-style format specification
* ... = printf-style variadic arguments
*/
extern (C++) void deprecationSupplemental(const ref Loc loc, const(char)* format, ...)
{
va_list ap;
Expand All @@ -104,17 +162,17 @@ extern (C++) void deprecationSupplemental(const ref Loc loc, const(char)* format
va_end(ap);
}

/******************************
/**
* Just print to stderr, doesn't care about gagging.
* (format,ap) text within backticks gets syntax highlighted.
* Params:
* loc = location of error
* loc = location of error
* headerColor = color to set `header` output to
* header = title of error message
* format = printf-style format specification
* ap = printf-style variadic arguments
* p1 = additional message prefix
* p2 = additional message prefix
* header = title of error message
* format = printf-style format specification
* ap = printf-style variadic arguments
* p1 = additional message prefix
* p2 = additional message prefix
*/
private void verrorPrint(const ref Loc loc, Color headerColor, const(char)* header,
const(char)* format, va_list ap, const(char)* p1 = null, const(char)* p2 = null)
Expand Down Expand Up @@ -151,7 +209,16 @@ private void verrorPrint(const ref Loc loc, Color headerColor, const(char)* head
fflush(stderr); // ensure it gets written out in case of compiler aborts
}

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

@wilzbach wilzbach Jan 30, 2018

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member Author

@ibuclaw ibuclaw Jan 31, 2018

Choose a reason for hiding this comment

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

Would you prefer that changed?

Copy link
Copy Markdown
Contributor

@wilzbach wilzbach Jan 31, 2018

Choose a reason for hiding this comment

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

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

* Params:
* loc = location of error
* format = printf-style format specification
* ap = printf-style variadic arguments
* p1 = additional message prefix
* p2 = additional message prefix
* header = title of error message
*/
extern (C++) void verror(const ref Loc loc, const(char)* format, va_list ap, const(char)* p1 = null, const(char)* p2 = null, const(char)* header = "Error: ")
{
global.errors++;
Expand All @@ -172,7 +239,13 @@ extern (C++) void verror(const ref Loc loc, const(char)* format, va_list ap, con
}
}

// Doesn't increase error count, doesn't print "Error:".
/**
* Same as $(D errorSupplemental), but takes a va_list parameter.
* Params:
* loc = location of error
* format = printf-style format specification
* ap = printf-style variadic arguments
*/
extern (C++) void verrorSupplemental(const ref Loc loc, const(char)* format, va_list ap)
{
Color color;
Expand All @@ -187,6 +260,13 @@ extern (C++) void verrorSupplemental(const ref Loc loc, const(char)* format, va_
verrorPrint(loc, color, " ", format, ap);
}

/**
* Same as $(D warning), but takes a va_list parameter.
* Params:
* loc = location of warning
* format = printf-style format specification
* ap = printf-style variadic arguments
*/
extern (C++) void vwarning(const ref Loc loc, const(char)* format, va_list ap)
{
if (global.params.warnings && !global.gag)
Expand All @@ -198,12 +278,28 @@ extern (C++) void vwarning(const ref Loc loc, const(char)* format, va_list ap)
}
}

/**
* Same as $(D warningSupplemental), but takes a va_list parameter.
* Params:
* loc = location of warning
* format = printf-style format specification
* ap = printf-style variadic arguments
*/
extern (C++) void vwarningSupplemental(const ref Loc loc, const(char)* format, va_list ap)
{
if (global.params.warnings && !global.gag)
verrorPrint(loc, Classification.warning, " ", format, ap);
}

/**
* Same as $(D deprecation), but takes a va_list parameter, and optionally additional message prefixes.
* Params:
* loc = location of deprecation
* format = printf-style format specification
* ap = printf-style variadic arguments
* p1 = additional message prefix
* p2 = additional message prefix
*/
extern (C++) void vdeprecation(const ref Loc loc, const(char)* format, va_list ap, const(char)* p1 = null, const(char)* p2 = null)
{
static __gshared const(char)* header = "Deprecation: ";
Expand All @@ -213,6 +309,13 @@ extern (C++) void vdeprecation(const ref Loc loc, const(char)* format, va_list a
verrorPrint(loc, Classification.deprecation, header, format, ap, p1, p2);
}

/**
* Same as $(D deprecationSupplemental), but takes a va_list parameter.
* Params:
* loc = location of deprecation
* format = printf-style format specification
* ap = printf-style variadic arguments
*/
extern (C++) void vdeprecationSupplemental(const ref Loc loc, const(char)* format, va_list ap)
{
if (global.params.useDeprecated == 0)
Expand All @@ -221,7 +324,7 @@ extern (C++) void vdeprecationSupplemental(const ref Loc loc, const(char)* forma
verrorPrint(loc, Classification.deprecation, " ", format, ap);
}

/***************************************
/**
* Call this after printing out fatal error messages to clean up and exit
* the compiler.
*/
Expand All @@ -234,7 +337,7 @@ extern (C++) void fatal()
exit(EXIT_FAILURE);
}

/**************************************
/**
* Try to stop forgetting to remove the breakpoints from
* release builds.
*/
Expand All @@ -243,7 +346,7 @@ extern (C++) void halt()
assert(0);
}

/**********************************************
/**
* Scan characters in `buf`. Assume text enclosed by `...`
* is D source code, and color syntax highlight it.
* Modify contents of `buf` with highlighted result.
Expand Down Expand Up @@ -289,9 +392,9 @@ private void colorSyntaxHighlight(OutBuffer* buf)
}


/****************************
/**
* Embed these highlighting commands in the text stream.
* HIGHLIGHT.Escape indicats a Color follows.
* HIGHLIGHT.Escape indicates a Color follows.
Copy link
Copy Markdown
Contributor

@jacob-carlborg jacob-carlborg Jan 31, 2018

Choose a reason for hiding this comment

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

Backticks around HIGHLIGHT.Escape.

*/
enum HIGHLIGHT : ubyte
{
Expand All @@ -304,7 +407,7 @@ enum HIGHLIGHT : ubyte
Other = Color.cyan, // other tokens
}

/**************************************************
/**
* Highlight code for CODE section.
* Rewrite the contents of `buf` with embedded highlights.
* Analogous to doc.highlightCode2()
Expand Down Expand Up @@ -380,8 +483,8 @@ private void colorHighlightCode(OutBuffer* buf)
--nested;
}

/*************************************
* Write the buffer contents with embedded highights to stderr.
/**
* Write the buffer contents with embedded highlights to stderr.
* Params:
* buf = highlighted text
*/
Expand Down