Add documentation examples for formatValue() #2296
Conversation
| @@ -2655,6 +2655,44 @@ const string toString(); | |||
| $(LI Otherwise, they are formatted like $(D Type(field1, filed2, ...)).)) | |||
|
|
|||
| Otherwise, are formatted just as their type name. | |||
|
|
|||
| Examples: | |||
| <dl>formatValue allows to reuse existing format specifiers : | |||
There was a problem hiding this comment.
Stray <dl> and extraneous space before the colon.
|
It looks like these two could be documented unit tests. |
|
Will documented unit tests appear in the documentation ? I know ddox has this feature, but I did only test the changes using the "old" layout (without ddox). |
Yes, it is a feature of plain DDoc as well. Put the example explanation text in the unit test's DDoc comment.
Don't ever put HTML directly into the documentation. Some places in the language documentation still do this, but it's being phased out. |
|
Updated. |
|
LGTM. Note that it's possible to do more succinct one-line documentation comments using |
| @@ -2697,6 +2697,52 @@ if (is(T == class) && !is(T == enum)) | |||
| } | |||
| } | |||
|
|
|||
| /** | |||
| formatValue allows to reuse existing format specifiers: | |||
There was a problem hiding this comment.
$(D formatValue)?
Technically not needed, as formatValue is the function being documented, so it is already always implicitly $D'ed. You can opt out by writing _formatValue in the documentation body, and it will appear as plain formatValue in the text.
Also ///
As long as it's a for a function, or documenting something that actually explains something, IMO, there's nothing wrong with a "proper" documentation header. /// really feels like it should be reserved for trivial getters or, enum values, or whatnot.
That said, I really wish we'd promote /++ +/ more than /** */. Unless you plan to backport to C, then + is always at least as good as *. End rent.
There was a problem hiding this comment.
Technically not needed, as formatValue is the function being documented, so it is already always implicitly $D'ed.
Is it? I think it's printed in green, but not in monotype. But the DDoc blocks lower had other D symbols too.
There was a problem hiding this comment.
Is it? I think it's printed in green, but not in monotype. But the DDoc blocks lower had other D symbols too.
I'm actually unsure. I know Andrei has made some "useless" comments when function names were being $D'ed in documentation. But no, I don't actually know what it does. IMO, there's nothing wrong with tagging with $D anyways. I just thought I'd mention it. Anybody know what happens exactly to the names of documented functions in DDoc?
There was a problem hiding this comment.
I just tested and if I omit
I also replaced /** */ with /++ +/. I will update in a few minutes.
BTW, I am not quite used to the GitHub workflow. Is it better to merge all the commits (rebase -i), amend the first one (probably not) to keep the history clean or just leave them all ?
There was a problem hiding this comment.
The rule of thumb is: Minimize your commits, but have each commit contain only one logical change. Of course, if things get complicated, one huge commit is fine. The only thing is we try to avoid merging commits that are "Oops", "fix", "typo" etc...
During the process proper, you may or may not merge your commits as you go. Both ways have their advantages. Personally, I just like it when I make a comment, to be pinged when the comment is addressed.
There was a problem hiding this comment.
Then it might be better to merge them all, here. The choice of comment delimiters is secondary.
|
Yes, I know it. I actually tried to mimic the coding style that was used elsewhere in std.format, but I can still change it. |
Add example showing how to forward format specifiers. Add example highlighting the similarity with formattedWrite(), and comparing their use. Change /** */ for /// and add $(D formatValue) Replace /** */ with /++ +/
|
Nice work! LGTM |
|
Auto-merge toggled on |
Add documentation examples for formatValue()
…ample Add documentation examples for formatValue()
Add example showing how to forward format specifiers.
Add example highlighting the similarity with formattedWrite(), and
comparing their use.