__traits(documentation, X)

[Steven Schveighoffer]

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