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).

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).

I think the languages that have "comment reflection", use this instead of custom attributes. In PHP for example

/**
 * @ORM\Entity(...)
 */
class MyEntity { ... }


Because there are no attributes. Why can't you just use UDAs instead of comments?

On Wednesday, 28 August 2019 at 09:04:06 UTC, Eugene Wissner wrote:
> Why can't you just use UDAs instead of comments?

Why does D use comments instead of UDAs? Because I *don't* want to change behavior, I want to extract documentation. Comments are for documentation.

On Wednesday, 28 August 2019 at 09:17:02 UTC, FeepingCreature wrote:
> On Wednesday, 28 August 2019 at 09:04:06 UTC, Eugene Wissner wrote:
>> Why can't you just use UDAs instead of comments?
>
> Why does D use comments instead of UDAs? Because I *don't* want to change behavior, I want to extract documentation. Comments are for documentation.

Swagger for Java uses annotations to describe the endpoints.

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...

On 2019-08-28 10:51, 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).
> 

You can try using the compiler as a library [1].

[1] https://code.dlang.org/packages/dmd

-- 
/Jacob Carlborg

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).

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

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.

On Wednesday, 28 August 2019 at 09:04:06 UTC, Eugene Wissner wrote:
> I think the languages that have "comment reflection", use this instead of custom attributes. In PHP for example
>
> /**
>  * @ORM\Entity(...)
>  */
> class MyEntity { ... }
>
>
> Because there are no attributes. Why can't you just use UDAs instead of comments?

We must also take into account differences in compilation time and memory for alternative solutions, in this case __traits vs UDAs.

On Wednesday, August 28, 2019 2:51:24 AM MDT FeepingCreature via Digitalmars-d 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 confess that I thought that there already was a trait for getting the ddoc comment associated with a symbol, but looking at the documentation, that doesn't appear to be the case.

- Jonathan M Davis

On Wednesday, 28 August 2019 at 10:00:07 UTC, Per Nordlöw wrote:
> On Wednesday, 28 August 2019 at 09:04:06 UTC, Eugene Wissner wrote:
>> I think the languages that have "comment reflection", use this instead of custom attributes. In PHP for example
>>
>> /**
>>  * @ORM\Entity(...)
>>  */
>> class MyEntity { ... }
>>
>>
>> Because there are no attributes. Why can't you just use UDAs instead of comments?
>
> We must also take into account differences in compilation time and memory for alternative solutions, in this case __traits vs UDAs.

UDAs are already supported. If you want to read the comments at compile-time, as a next step you want to parse them, validate the types and content, generate and write some output...