On Wednesday, 28 August 2019 at 09:55:47 UTC, Eugene Wissner wrote:
> On Wednesday, 28 August 2019 at 09:35:54 UTC, Sebastiaan Koppe wrote:
>> Just create a Swagger struct (plus helper structs) and use like:
>>
>> ```
>> @Swagger(ApiResponses([
>>     ApiResponse(code = 200, message = "...", response = Entity),
>>     ApiResponse(code = 404, message = "listing not found")
>>   ]),
>>   Put("/entities/{id}"),
>>   Consumes([MediaType.APPLICATION_JSON_VALUE]),
>>   Produces([MediaType.APPLICATION_JSON_VALUE])
>> )
>> Entity endpoint(string id) { ... }
>> ```
>>
>> I think it beats parsing (or writing) comments...
>
> and provides some static typing, because structs can be used, and probably better error messages than reinventing a Ddoc parser.


Right but also UDAs look terrible as docs.

All this is info I already have. The only thing I can't get is the documentation comment on them.

How about this:

/**
 * Do a thing.
 *
 * Params:
 *  foo = A parameter
 */
void method();

would get converted by the compiler to

@(DDoc.Description("Do a thing"))
@(DDoc.Param!Foo(1, "foo", "A parameter"))
void method();

That'd give the best of both worlds.

On Wednesday, 28 August 2019 at 10:29:24 UTC, FeepingCreature wrote:
> @(DDoc.Description("Do a thing"))
> @(DDoc.Param!Foo(1, "foo", "A parameter"))
> void method();
>
> That'd give the best of both worlds.

Sorry, that's a terrible way to do it.

I should have written @(DDoc.Param("foo", "A parameter")).

Carry on.

On Wednesday, 28 August 2019 at 08:51:24 UTC, FeepingCreature wrote:
> I propose a way to get the comment on a symbol at compile time. I believe this was already rejected, though I don't know why; I'd expect it to be something like "code should not change behavior due to a comment." I think that now that we have user-defined annotations there is a much lower risk of that.
>
> Why do I want this? Generating special documentation/annotated interfaces from D code is a *lot* easier if you can get the compiler to do your introspection work for you. I want to generate Swagger files documenting our REST services, and I want to use D comments to document them. Right now, I will have to do a weird hybrid dance where I generate the D type graph on the D side with compiletime introspection, output it to a file, simultaneously generate the Ddoc JSON file with -D -X to fish out the comments, then fuse the two together. There is no need for this, but for the absence of __traits(getComment).

The alternative approach would be to have a UDA that would be treated as ddoc.

On Wednesday, 28 August 2019 at 11:26:34 UTC, John Colvin wrote:
> The alternative approach would be to have a UDA that would be treated as ddoc.

Personally speaking, that doesn't buy me anything.

The primary concern is having good-looking D comments. The secondary concern is being able to generate Swagger. Generated Ddoc html is a very distant third concern. UDAs that are treated as Ddoc would buy me the second at the cost of completely destroying the first; I might as well just use regular UDAs, as was already proposed.

On Wed, Aug 28, 2019 at 1:55 AM FeepingCreature via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
>
> I propose a way to get the comment on a symbol at compile time. I believe this was already rejected, though I don't know why; I'd expect it to be something like "code should not change behavior due to a comment." I think that now that we have user-defined annotations there is a much lower risk of that.
>
> Why do I want this? Generating special documentation/annotated interfaces from D code is a *lot* easier if you can get the compiler to do your introspection work for you. I want to generate Swagger files documenting our REST services, and I want to use D comments to document them. Right now, I will have to do a weird hybrid dance where I generate the D type graph on the D side with compiletime introspection, output it to a file, simultaneously generate the Ddoc JSON file with -D -X to fish out the comments, then fuse the two together. There is no need for this, but for the absence of __traits(getComment).

I was really interested in this feature back when it was rejected the
first time.
My use is in video games, we create high-level gameplay code which
plugs itself into the editor environment.
This code publishes properties and the things that it can do from an
editor perspective, and in the editor, it is very nice to be able to
hover over values in property tables, and see the documentation for
the values in tooltips, which explains what the values are and how
they work.
We can do this with UDA's, but it's more natural to write documenting
comments with documenting comments.
In most cases, values have a UDA with this text, which contains a
string which is a cut&paste from the comment immediately above, and
it's very easy to amend one and forget to amend the other, and they
fall out of sync.

As a development workflow feature, having compiler access to symbol comments would be very useful in many cases.

On 8/28/19 5:44 AM, Mike Franklin wrote:
> I once gave a talk at DConf explaining how I copy and pasted register table from a datasheet into an application, and had it spit out D code.  I later ported the code to D (https://github.com/JinShil/stm32_datasheet_to_d).  With your proposal, I could just paste the text from the datasheet into my DDoc comment and have D generate the code for me.  Chuckle, Chuckle.

Ahem, I didn't get to it (thanks, fire drill), but your presentation (which is still one of my favorites), was actually referenced in my presentation "extras" ;)

Start at page 63: http://dconf.org/2019/talks/schveighoffer.pdf

> Now think what people more "creative" than I could come up with. :-)
> 
> I'm not sure if it would be good practice.

I think the idea of using an actual spec to write your register code is insanely useful, even if it takes hours to compile ;) It can't be worse than hours spent realizing you misread something in the spec.

-Steve

On Wednesday, 28 August 2019 at 17:35:56 UTC, Manu wrote:
> As a development workflow feature, having compiler access to symbol comments would be very useful in many cases.

Speaking of which, has anyone tried/discussed giving access to a frozen version of the AST through (say) __traits(getAST, symbol)? I'd try it myself but I haven't spent the time learning how dmd works.

On Wednesday, 28 August 2019 at 22:07:28 UTC, Steven Schveighoffer wrote:

> Ahem, I didn't get to it (thanks, fire drill), but your presentation (which is still one of my favorites), was actually referenced in my presentation "extras" ;)
>
> Start at page 63: http://dconf.org/2019/talks/schveighoffer.pdf

Wow! Thanks for that. :-)

>> Now think what people more "creative" than I could come up with. :-)
>> 
>> I'm not sure if it would be good practice.
>
> I think the idea of using an actual spec to write your register code is insanely useful, even if it takes hours to compile ;) It can't be worse than hours spent realizing you misread something in the spec.

So true.

I have to same I'm on the fence with this idea.  It is tempting.

Mike

On Wednesday, 28 August 2019 at 09:44:10 UTC, Mike Franklin wrote:
> In general, I'm in favor of adding any compiler information to the `__traits` system.  This one is particularly interesting though.
>
> I once gave a talk at DConf explaining how I copy and pasted register table from a datasheet into an application, and had it spit out D code.  I later ported the code to D (https://github.com/JinShil/stm32_datasheet_to_d).  With your proposal, I could just paste the text from the datasheet into my DDoc comment and have D generate the code for me.  Chuckle, Chuckle.
>
> Now think what people more "creative" than I could come up with.  :-)
>
> I'm not sure if it would be good practice.
>
> Mike

I personally feel that with string mixin, CTFE, import() and now UDAs, we have already given the programmer entirely sufficient lengths of rope to hang themselves in whichever way they desire. Adding another length of rope to create an exciting new way to cause self-harm will not at this point increase the death and injury rate an appreciable amount.

That ship has sailed, made landfall in the Americas, and is currently on the return trip.

On Wednesday, 28 August 2019 at 22:18:28 UTC, Max Haughton wrote:
> On Wednesday, 28 August 2019 at 17:35:56 UTC, Manu wrote:
>> As a development workflow feature, having compiler access to symbol comments would be very useful in many cases.
>
> Speaking of which, has anyone tried/discussed giving access to a frozen version of the AST through (say) __traits(getAST, symbol)? I'd try it myself but I haven't spent the time learning how dmd works.

Whatever you want to do with traits(getAST) would likely be a job for dmd as a library.