What
----

```
/// my fancy string
enum documentedEnum = 1;
enum funcDoc = __traits(documentation, documentedFunc);
assert(funcDoc == "my fancy string")
```

See https://github.com/dlang/dmd/pull/6872 for better examples


Status
-------

The naive implementation leads to a small, but noticeable increase of DMD's compilation time.

Andrei's words:

> I'd say keep it on the back burner until we find a couple of good ideas for using it. Discussing it in the forum may help.

So do you have a good use cases for this?
If this is a useful feature, the implementation can be improved to be zero-cost for normal runs.

Post here or at https://github.com/dlang/dmd/pull/6872

Just a fun bit of history:

A few years ago I looked into implementing this myself.
Discovering that without -D documentation is lost.

Why did I want to do this?
From memory it was to allow me to give greater control over exportation of models+routes in Cmsed as part of documentation (or something along those lines).

I wouldn't want to do it this way now, but it does still feel like a hole in traits to me.

But imagine a use case of translations:

/**
 * Translation_English:
 *     Foo bar
 * Translation_X:
 *     SDFJL
 */
string welcome(Language language) {
	return getSectionFromDDOC(__traits(comments, welcome), "Translation_" ~ language.text);
}

On Wednesday, 17 January 2018 at 02:19:11 UTC, Seb wrote:
> What
> ----
>
> ```
> /// my fancy string
> enum documentedEnum = 1;
> enum funcDoc = __traits(documentation, documentedFunc);
> assert(funcDoc == "my fancy string")
> ```
>
> See https://github.com/dlang/dmd/pull/6872 for better examples
>
>
> Status
> -------
>
> The naive implementation leads to a small, but noticeable increase of DMD's compilation time.
>
> Andrei's words:
>
>> I'd say keep it on the back burner until we find a couple of good ideas for using it. Discussing it in the forum may help.
>
> So do you have a good use cases for this?
> If this is a useful feature, the implementation can be improved to be zero-cost for normal runs.
>
> Post here or at https://github.com/dlang/dmd/pull/6872

In my case might be useful for generating foreign doc strings for automatically generated wrappers in other languages and for D functions intended for use directly but also mounted into an interpreted DSL.. You could duplicate docstring with attributes but hardly pretty.

On 1/16/18 9:19 PM, Seb wrote:
> What
> ----
> 
> ```
> /// my fancy string
> enum documentedEnum = 1;
> enum funcDoc = __traits(documentation, documentedFunc);
> assert(funcDoc == "my fancy string")
> ```
> 
> See https://github.com/dlang/dmd/pull/6872 for better examples
> 
> 
> Status
> -------
> 
> The naive implementation leads to a small, but noticeable increase of DMD's compilation time.
> 
> Andrei's words:
> 
>> I'd say keep it on the back burner until we find a couple of good ideas for using it. Discussing it in the forum may help.
> 
> So do you have a good use cases for this?
> If this is a useful feature, the implementation can be improved to be zero-cost for normal runs.
> 
> Post here or at https://github.com/dlang/dmd/pull/6872

I shudder at the thought of compiled code being affected by documentation.

I don't like it, sorry.

-Steve

Steven Schveighoffer wrote:

> I shudder at the thought of compiled code being affected by documentation.
>
> I don't like it, sorry.

it's not really different from `version(DDoc)`, or string mixins, or UDAs. i can put documentation in UDA, and process code differently when UDA changes. yes, UDA is not a comment -- but it doesn't affect code generation directly too. there is just no way to stop people from writing abominations once we got metaprogramming. and adding artificial limitations on that just makes people more inventive, but won't stop infestation. ;-)

On 1/16/18 10:59 PM, ketmar wrote:
> Steven Schveighoffer wrote:
> 
>> I shudder at the thought of compiled code being affected by documentation.
>>
>> I don't like it, sorry.
> 
> it's not really different from `version(DDoc)`, or string mixins, or UDAs. i can put documentation in UDA, and process code differently when UDA changes. yes, UDA is not a comment -- but it doesn't affect code generation directly too. there is just no way to stop people from writing abominations once we got metaprogramming. and adding artificial limitations on that just makes people more inventive, but won't stop infestation. ;-)

version(DDoc) is very different. It's a command line option passed to the build, and affecting the build with command line options is expected.

This proposal has comment *contents* affecting the build. The charter of comments is to NOT affect code, ever. They can be used to affect other systems, such as the ddoc generator, ide hints, etc., but you can be sure (?) that comments won't change code.

I think this is an important line not to cross.

One of the features promoted in this is to have the documentation be used for command-line help. I think it would be better to allow ddoc generation be affected by code rather than the other way around in this regard.

-Steve

On Wed, 17 Jan 2018 11:52:40 -0500, Steven Schveighoffer wrote:

> version(DDoc) is very different. It's a command line option passed to the build, and affecting the build with command line options is expected.
> 
> This proposal has comment *contents* affecting the build. The charter of comments is to NOT affect code, ever. They can be used to affect other systems, such as the ddoc generator, ide hints, etc., but you can be sure (?) that comments won't change code.
> 
> I think this is an important line not to cross.

I have to agree with this. If translated documentation is the primary use case, I'd imagine we could find better ways to do it.

On Wed, Jan 17, 2018 at 11:52:40AM -0500, Steven Schveighoffer via Digitalmars-d wrote: [...]
> This proposal has comment *contents* affecting the build. The charter of comments is to NOT affect code, ever. They can be used to affect other systems, such as the ddoc generator, ide hints, etc., but you can be sure (?) that comments won't change code.
> 
> I think this is an important line not to cross.

+1.  The thought of comments affecting code scares me, and not just a little.


> One of the features promoted in this is to have the documentation be used for command-line help. I think it would be better to allow ddoc generation be affected by code rather than the other way around in this regard.
[...]

That's actually a much better idea.  Have some way of injecting, say, a string UDA into ddoc so that you can have one source that generates both documentation and command-line help.  The latter is already possible, and easy to implement; now we just need the former.


T

-- 
MAS = Mana Ada Sistem?

On Wed, Jan 17, 2018 at 06:24:50PM +0000, Simen Kjærås via Digitalmars-d wrote:
> On Wednesday, 17 January 2018 at 16:52:40 UTC, Steven Schveighoffer wrote:
> > The charter of comments is to NOT affect code, ever. They can be used to affect other systems, such as the ddoc generator, ide hints, etc., but you can be sure (?) that comments won't change code.
> > 
> > I think this is an important line not to cross.
> 
> That's already perfectly possible today:
> 
> enum a = import(__FILE__);
> static if (a.indexOf("//") > -1) {
>     fireZeMissiles();
> }
[...]

I can see it now.  In the year 2030, a major exploit is found in a widely-deployed online D application, causing massive data loss and damages. The cause? A misplaced comment... :-P


T

-- 
Never trust an operating system you don't have source for! -- Martin Schulze

On Wednesday, 17 January 2018 at 16:52:40 UTC, Steven Schveighoffer wrote:
> The charter of comments is to NOT affect code, ever. They can be used to affect other systems, such as the ddoc generator, ide hints, etc., but you can be sure (?) that comments won't change code.
>
> I think this is an important line not to cross.

That's already perfectly possible today:

enum a = import(__FILE__);
static if (a.indexOf("//") > -1) {
    fireZeMissiles();
}

--
  Simen