>> But in any case, the idea that comments affect the file you are compiling *right now*, and not some other tool-generated file makes me very nervous. Comments are supposed to not affect the code. Consider that with this feature, the documentation now becomes part of the API.

That's already the case today that documentation can affect the code because `import(__FILE__)` is legal. Both string import and `__traits(documentation)` are tools and can be used for solving real problems or abused.

Let's not invoke (impossible) ideals at the expense of pragmatism; D is supposed to be pragmatic, not dogmatic.

On 1/18/18 3:21 PM, Timothee Cour wrote:
>>> But in any case, the idea that comments affect the file you are compiling
>>> *right now*, and not some other tool-generated file makes me very nervous.
>>> Comments are supposed to not affect the code. Consider that with this
>>> feature, the documentation now becomes part of the API.
> 
> That's already the case today that documentation can affect the code
> because `import(__FILE__)` is legal. Both string import and
> `__traits(documentation)` are tools and can be used for solving real
> problems or abused.
> 
> Let's not invoke (impossible) ideals at the expense of pragmatism; D
> is supposed to be pragmatic, not dogmatic.
> 

Of course, you can cobble together something that uses the docs in your build process, you don't need the compiler to help create such a monster. After all, they are just text files.

The point remains -- if you normalize this feature, it will be abused far easier and more frequently than it would be if it's less trivial.

In any case, I stand by my assertion -- comments should be comments, not code.

A related improvement: Documented unit tests. Instead of adding a feature to D where examples in the documentation were tested directly (and I'm pretty sure this was proposed), we added the ability to document unit tests. I think this was a far saner direction.

A further note: Does this need go away when we make the compiler a library? Then you can extract the docs all you want and manipulate them into whatever you want using a build tool.

-Steve

On Thursday, 18 January 2018 at 20:35:54 UTC, Steven Schveighoffer wrote:
>
> A further note: Does this need go away when we make the compiler a library? Then you can extract the docs all you want and manipulate them into whatever you want using a build tool.
>
> -Steve

You can already do this fairly easy with libdparse. No need for a compiler with semantics here.
Here's a D-Scanner test I wrote a while ago that checks whether all comments of public symbols have a Params section of all their parameters and a returns section if they don't return void:

https://github.com/dlang-community/D-Scanner/blob/master/src/analysis/properly_documented_public_functions.d

It's a shame it's only partially enabled on Phobos as there are many old modules which I had to blacklist initially.

On Thursday, 18 January 2018 at 20:35:54 UTC, Steven Schveighoffer wrote:
> In any case, I stand by my assertion -- comments should be comments, not code.

Note that we aren't talking about comments. We're talking about ddoc strings. They just have very similar appearance to comments, but they are distinct entities defined by D to be part of the AST (and the compiler will parse their contents too if you ask it to!), unlike regular comments which are discarded before parsing.

That's really the big difference that puts me over the top: documentation strings in D are defined to be attached to the symbol by the compiler. They're ALREADY different than plain comment-comments, just the compiler withholds this information from the code.

On 1/18/18 4:01 PM, Adam D. Ruppe wrote:
> On Thursday, 18 January 2018 at 20:35:54 UTC, Steven Schveighoffer wrote:
>> In any case, I stand by my assertion -- comments should be comments, not code.
> 
> Note that we aren't talking about comments. We're talking about ddoc strings. They just have very similar appearance to comments, but they are distinct entities defined by D to be part of the AST (and the compiler will parse their contents too if you ask it to!), unlike regular comments which are discarded before parsing.

Hm... I don't see where Ddoc comments are defined separately from comments in the grammar. How they are stored internally is up to the compiler, and as far as I know, the D *language* makes no guarantees on what comes out:

"The specification for the form of embedded documentation comments only specifies how information is to be presented to the compiler. It is implementation-defined how that information is used and the form of the final presentation."

This brings up another thing: What if the compiler you are using decides to do something completely different with the documentation (or maybe even nothing)? Then __traits(documentation, X) may be completely different and cause different code to be generated.

-Steve

On Thursday, 18 January 2018 at 21:01:01 UTC, Adam D. Ruppe wrote:
> Note that we aren't talking about comments. We're talking about ddoc strings. They just have very similar appearance to comments, but they are distinct entities defined by D to be part of the AST (and the compiler will parse their contents too if you ask it to!), unlike regular comments which are discarded before parsing.

I think `__traits(documentation, X)` makes sens if the documentation was generated by library (AST -> HTML)

But as far as I know the documentation can't be generated by CTFE directly.

On Thursday, 18 January 2018 at 18:31:28 UTC, Steven Schveighoffer wrote:
> On 1/18/18 11:48 AM, Adam D. Ruppe wrote:
>> [...]
>
> This is how I'd imagine doing something like this. I don't see it being a huge pain, just an extra build step.
>
>> [...]
>
> Did you mean not really harmful?
>
> But in any case, the idea that comments affect the file you are compiling *right now*, and not some other tool-generated file makes me very nervous. Comments are supposed to not affect the code. Consider that with this feature, the documentation now becomes part of the API.
>
While I'm on your side of the issue, it is a fact that ddoc (or doxygen, javadoc) comments are more a language within a language (i.e. there is syntax in them) than simple comments.