Add Ddoc headers for front-end modules by dkorpel · Pull Request #10903 · dlang/dmd

dkorpel · 2020-03-12T21:15:19Z

As suggested by Walter: #9844 (comment)

Adds missing module descriptions
Consistently puts the description above the boilerplate
Adds links to the specification where applicable

The descriptions are sometimes vague since I'm not always sure myself what each module does exactly, but it's a start.

dlang-bot · 2020-03-12T21:15:22Z

Thanks for your pull request and interest in making D better, @dkorpel! We are looking forward to reviewing it, and you should be hearing from a maintainer soon.
Please verify that your PR follows this checklist:

My PR is fully covered with tests (you can see the coverage diff by visiting the details link of the codecov check)
My PR is as minimal as possible (smaller, focused PRs are easier to review than big ones)
I have provided a detailed rationale explaining my changes
New or modified functions have Ddoc comments (with Params: and Returns:)

Please see CONTRIBUTING.md for more information.

If you have addressed all reviews or aren't sure how to proceed, don't hesitate to ping us with a simple comment.

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.

Testing this PR locally

If you don't have a local development environment setup, you can use Digger to test this PR:

dub run digger -- build "master + dmd#10903"

Geod24 · 2020-03-13T00:18:55Z

I would just remove the boilerplate. Especially with the way you put it, it's part of the "Specification" section, not the description.

Geod24

Included few comments (didn't finish my review).

In general:

Get rid of the boilerplate
Make sure you have an empty line between the title and the description.
Make sure the descriptions comes directly after the title, not after a section.

Geod24 · 2020-03-13T00:19:36Z

src/dmd/arrayop.d

@@ -1,4 +1,8 @@
 /**
+ * Implement array opterations, such as `a[] = b[] + c[]`.


Geod24 · 2020-03-13T00:20:11Z

src/dmd/ast_node.d

@@ -1,4 +1,6 @@
 /**
+ * Defines an abstract ASTNode class.


Suggested change

* Defines an abstract ASTNode class.

* Defines the base class for all nodes which are part of the AST.

Geod24 · 2020-03-13T00:20:30Z

src/dmd/astbase.d

+module dmd.astbase;
+
+/**
+ */


Geod24 · 2020-03-13T00:24:30Z

src/dmd/attrib.d

@@ -1,4 +1,17 @@
 /**
+ * Defines declarations of various 'attributes'.
+ * The term attribute is used very loosly, since it includes:


Put an empty line (well, with a *) between line 2 and 3 to make this part of the description.
Also I wouldn't say it is not used loosely, just that your expectation of what an attribute is might differ.
It has more to do with things applying to a larger scope than a single declaration, I'd say.

Geod24 · 2020-03-13T00:46:02Z

src/dmd/builtin.d

@@ -1,4 +1,7 @@
 /**
+ * Evaluate certain external functions for CTFE.


Suggested change

* Evaluate certain external functions for CTFE.

* Implement CTFE for intrinsic (builtin) functions

Also the empty line to separate title from description.
You might want to link / read https://en.wikipedia.org/wiki/Intrinsic_function

Geod24 · 2020-03-13T00:47:05Z

src/dmd/cli.d

- * Compiler implementation of the
- * $(LINK2 http://www.dlang.org, D programming language).
- *
 * This modules defines the help texts for the CLI options offered by DMD.


Newline after this to make the title short.

Geod24 · 2020-03-13T00:49:51Z

src/dmd/dmangle.d

@@ -1,4 +1,9 @@
 /**
+ * Does name mangling for D symbols, which generates a unique name for a linker symbol based


Too long, and inconsistent with the cppmangle side which does not explain what mangling is.
But really, I would expect anyone working on a compiler to know that. We can still add a See_Also to wikipedia if you feel like it, but we shouldn't paraphrase it.

Geod24 · 2020-03-13T10:11:35Z

src/dmd/attrib.d

- * The term attribute is used very loosly, since it includes:
+ * Defines declarations of various attributes.
+ *
+ * The term 'attribute' refers to things that apply to a larger scope than a single declaration.


Suggested change

* The term 'attribute' refers to things that apply to a larger scope than a single declaration.

* The term 'attribute' refers to things that can apply to a larger scope than a single declaration.

E.g. depending on how you declare it, you might have deprecated as an attribute which is a parent of Dsymbols, or directly as part of the Dsymbol's storage classes.

Geod24 · 2020-03-13T10:12:03Z

src/dmd/dmangle.d

 /**
- * Does name mangling for D symbols, which generates a unique name for a linker symbol based
- * on the namespace, identifier and type.
+ * Does name mangling for D symbols.


Suggested change

* Does name mangling for D symbols.

* Does name mangling for `extern(D)` symbols.

dkorpel · 2020-03-13T10:18:29Z

I would just remove the boilerplate. Especially with the way you put it, it's part of the "Specification" section, not the description.

Do you mean this text:

Compiler implementation of the $(LINK2 http://www.dlang.org, D programming language)

Or the other links as well? Except for 'Authors', all default sections could be auto-generated, but I do think Walter likes to have them in the source file.

Geod24 · 2020-03-13T10:24:44Z

Do you mean this text:

Yep just this. The rest is fine.

add Ddoc headers for front-end modules

167b797

dkorpel requested review from CyberShadow, Geod24, MartinNowak, RazvanN7, WalterBright, andralex, ibuclaw, jacob-carlborg and rainers as code owners March 12, 2020 21:15

Geod24 reviewed Mar 13, 2020

View reviewed changes

improve module titles

5a26eae

dkorpel force-pushed the documentModules branch from 5ae2f8f to 5a26eae Compare March 13, 2020 10:20

dkorpel force-pushed the documentModules branch from d5d7d93 to 5a26eae Compare March 13, 2020 10:35

dkorpel added 3 commits March 13, 2020 11:45

remove boilerplate from Ddoc headers

41fd52c

remove more boilerplate Ddoc headers

049ee48

fix LINK2 macros

07af28f

dkorpel force-pushed the documentModules branch from 9f4d4e3 to 07af28f Compare March 13, 2020 13:46

dkorpel mentioned this pull request Mar 13, 2020

Add Ddoc headers for modules in dmd/root #10911

Merged

Geod24 approved these changes Mar 28, 2020

View reviewed changes

Geod24 added the Merge:auto-merge-squash label Mar 28, 2020

dlang-bot merged commit d2e8a54 into dlang:master Mar 28, 2020

dkorpel deleted the documentModules branch March 28, 2020 14:42

dkorpel mentioned this pull request Aug 31, 2021

Add Ddoc headers in dmd/backend modules #13035

Merged

		@@ -1,4 +1,8 @@
		/**
		* Implement array opterations, such as `a[] = b[] + c[]`.

	* Defines an abstract ASTNode class.
	* Defines the base class for all nodes which are part of the AST.

		@@ -1,4 +1,7 @@
		/**
		* Evaluate certain external functions for CTFE.

	* Evaluate certain external functions for CTFE.
	* Implement CTFE for intrinsic (builtin) functions

		@@ -1,4 +1,9 @@
		/**
		* Does name mangling for D symbols, which generates a unique name for a linker symbol based

	* The term 'attribute' refers to things that apply to a larger scope than a single declaration.
	* The term 'attribute' refers to things that can apply to a larger scope than a single declaration.

	* Does name mangling for D symbols.
	* Does name mangling for `extern(D)` symbols.

Uh oh!

Conversation

dkorpel commented Mar 12, 2020

Uh oh!

dlang-bot commented Mar 12, 2020

Bugzilla references

Testing this PR locally

Uh oh!

Geod24 commented Mar 13, 2020

Uh oh!

Geod24 left a comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkorpel commented Mar 13, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Geod24 commented Mar 13, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dkorpel commented Mar 13, 2020 •

edited

Loading