New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding support for __traits(documentation, ...) #3531

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
@MasonMcGill

MasonMcGill commented May 7, 2014

__traits(comment, expr) now evaluates to the documentation comment on expr, if it exists and is available. Comments will only be available if DMD is invoked with the "-D" flag. If no comment is available for expr, __traits(comment, expr) evaluates to the empty string.

Unlike __traits(identifier, expr), __traits(comment, expr) will not report an error if expr is not a symbol or anonymous function. It will instead evaluate to the empty string. This is in the interest of ease of use.

This feature is intended to aide automatic wrapper generation, metaprogramming (e.g. forwarding documentation from a template argument), and simplifying documentation generators. It is not intended to be involved in providing application functionality.

@Hackerpilot

This comment has been minimized.

Show comment
Hide comment
@Hackerpilot

Hackerpilot May 7, 2014

Member

Looks useful.

Member

Hackerpilot commented May 7, 2014

Looks useful.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

Should it be called 'comment'?
It looks like it's only intended to work with ddoc comment blocks (/** */ or ///), so possibly misleading to call the trait 'comment', since it's only a specific form of comment?

Contributor

TurkeyMan commented May 7, 2014

Should it be called 'comment'?
It looks like it's only intended to work with ddoc comment blocks (/** */ or ///), so possibly misleading to call the trait 'comment', since it's only a specific form of comment?

@TurkeyMan

View changes

Show outdated Hide outdated test/runnable/traits.d
@jacob-carlborg

View changes

Show outdated Hide outdated test/runnable/traits.d
@jacob-carlborg

This comment has been minimized.

Show comment
Hide comment
@jacob-carlborg

jacob-carlborg May 7, 2014

Contributor

Please squash your commits when done.

Contributor

jacob-carlborg commented May 7, 2014

Please squash your commits when done.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

In DMD, internally, the "comment" field of a symbol ends in a newline. I suppose this has to do with how they are initially parsed. Generally, spaces newlines will be stripped before HTML or PDF documentation generation, so it doesn't seem like a major issue.

With respect to the term "comment", this is the field name in the DMD JSON output.

I think "notes" or "documentation" might also be good trait names, but I don't know if either is good enough to warrant breaking consistency with DMD JSON output and DMD internals. Thoughts?

MasonMcGill commented May 7, 2014

In DMD, internally, the "comment" field of a symbol ends in a newline. I suppose this has to do with how they are initially parsed. Generally, spaces newlines will be stripped before HTML or PDF documentation generation, so it doesn't seem like a major issue.

With respect to the term "comment", this is the field name in the DMD JSON output.

I think "notes" or "documentation" might also be good trait names, but I don't know if either is good enough to warrant breaking consistency with DMD JSON output and DMD internals. Thoughts?

@jacob-carlborg

This comment has been minimized.

Show comment
Hide comment
@jacob-carlborg

jacob-carlborg May 7, 2014

Contributor

Could you please make a pull request for updating the documentation as well.

Contributor

jacob-carlborg commented May 7, 2014

Could you please make a pull request for updating the documentation as well.

@jacob-carlborg

This comment has been minimized.

Show comment
Hide comment
@jacob-carlborg

jacob-carlborg May 7, 2014

Contributor

I agree with @TurkeyMan. It might be confusing if it only works for ddoc comments. "documentation", "ddoc" or similar would be better.

Contributor

jacob-carlborg commented May 7, 2014

I agree with @TurkeyMan. It might be confusing if it only works for ddoc comments. "documentation", "ddoc" or similar would be better.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

I think the newline should be stripped before returning it as a __traits(), otherwise user code will constantly have to strip it manually.

"documentation" or "ddoc" is probably what I'd choose.
The way I see it, most end-users aren't DMD contributors, so I don't think that consistency with the compiler source has any significant weight if the trade-off is language clarity.
I'd also imagine very few users would be particularly upset that a different term was used in the json output. Most users never use/look at that either, it's something that's more likely to be digested by tooling.

For my money, code clarity trumps.

Contributor

TurkeyMan commented May 7, 2014

I think the newline should be stripped before returning it as a __traits(), otherwise user code will constantly have to strip it manually.

"documentation" or "ddoc" is probably what I'd choose.
The way I see it, most end-users aren't DMD contributors, so I don't think that consistency with the compiler source has any significant weight if the trade-off is language clarity.
I'd also imagine very few users would be particularly upset that a different term was used in the json output. Most users never use/look at that either, it's something that's more likely to be digested by tooling.

For my money, code clarity trumps.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

My impression (mostly based on experience with Python documentation) is that "ddoc" refers to the standard way to associate comments with symbols, and "documentation" may refer to any kind of documentation (web-based tutorials, examples, etc.)

I read __traits(comment, expr) as "get me the comment associated with expr", and since ddoc is the way to associate comments with symbols, it's unambiguous.

However, if more people prefer "documentation", I'm happy to change it. I'm honestly more interested in using this feature than designing it : )

MasonMcGill commented May 7, 2014

My impression (mostly based on experience with Python documentation) is that "ddoc" refers to the standard way to associate comments with symbols, and "documentation" may refer to any kind of documentation (web-based tutorials, examples, etc.)

I read __traits(comment, expr) as "get me the comment associated with expr", and since ddoc is the way to associate comments with symbols, it's unambiguous.

However, if more people prefer "documentation", I'm happy to change it. I'm honestly more interested in using this feature than designing it : )

@jacob-carlborg

This comment has been minimized.

Show comment
Hide comment
@jacob-carlborg

jacob-carlborg May 7, 2014

Contributor

I read __traits(comment, expr) as "get me the comment associated with expr", and since ddoc is the way to associate comments with symbols, it's unambiguous.

Yes, but does it work both for ddoc comments and regular comments?

Contributor

jacob-carlborg commented May 7, 2014

I read __traits(comment, expr) as "get me the comment associated with expr", and since ddoc is the way to associate comments with symbols, it's unambiguous.

Yes, but does it work both for ddoc comments and regular comments?

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

I guess the argument is that there's no rule to associate a regular comment with a particular symbol, so the concept is kinda meaningless. Doesn't mean it will always be that way in the future though...
I think I prefer 'ddoc', it's quite specific that it intends ddoc style associated comments.

Contributor

TurkeyMan commented May 7, 2014

I guess the argument is that there's no rule to associate a regular comment with a particular symbol, so the concept is kinda meaningless. Doesn't mean it will always be that way in the future though...
I think I prefer 'ddoc', it's quite specific that it intends ddoc style associated comments.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

With regards to the newline and extra spaces, should only the first/last be stripped, or all of them? Python leaves them in, so formatting applications can choose to deal with them as they wish.

To me, formatting docstrings seems like a separate issue. It's handled by different code, and used for more than just __traits (like JSON and HTML output). I'm sure anyone interested in working on it could do so before or after the new trait is added.

MasonMcGill commented May 7, 2014

With regards to the newline and extra spaces, should only the first/last be stripped, or all of them? Python leaves them in, so formatting applications can choose to deal with them as they wish.

To me, formatting docstrings seems like a separate issue. It's handled by different code, and used for more than just __traits (like JSON and HTML output). I'm sure anyone interested in working on it could do so before or after the new trait is added.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

I don't know how many D users know that D's documentation comments are called "ddoc". Like Python's "docstrings", I wouldn't be surprised if many people have seen them but don't know they have a name.

"documentation" and "comment" seem more discoverable.

MasonMcGill commented May 7, 2014

I don't know how many D users know that D's documentation comments are called "ddoc". Like Python's "docstrings", I wouldn't be surprised if many people have seen them but don't know they have a name.

"documentation" and "comment" seem more discoverable.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

It looks like documentation comment retrieval is performed with __doc__ in Python and documentation in Common Lisp:
http://en.wikipedia.org/wiki/Docstring

MasonMcGill commented May 7, 2014

It looks like documentation comment retrieval is performed with __doc__ in Python and documentation in Common Lisp:
http://en.wikipedia.org/wiki/Docstring

@yebblies

This comment has been minimized.

Show comment
Hide comment
@yebblies

yebblies May 7, 2014

Member

With regards to the newline and extra spaces, should only the first/last be stripped, or all of them? Python leaves them in, so formatting applications can choose to deal with them as they wish.

Leave internal, strip at beginning and end. Leading/trailing whitespace does not add information.

"documentation" and "comment" seem more discoverable.

"documentation" is fine but "comment" is imprecise. There is no need to match the internal compiler name unless the alternative is inventing new terminology.

Member

yebblies commented May 7, 2014

With regards to the newline and extra spaces, should only the first/last be stripped, or all of them? Python leaves them in, so formatting applications can choose to deal with them as they wish.

Leave internal, strip at beginning and end. Leading/trailing whitespace does not add information.

"documentation" and "comment" seem more discoverable.

"documentation" is fine but "comment" is imprecise. There is no need to match the internal compiler name unless the alternative is inventing new terminology.

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost May 7, 2014

-D is not required for this feature to work.

Edit: Wait, the tests test for empty strings. I'll investigate.

Edit2: Well, they should not require -D, or the trait is useless for metaprogramming. I'll see if this can be worked around.

ghost commented May 7, 2014

-D is not required for this feature to work.

Edit: Wait, the tests test for empty strings. I'll investigate.

Edit2: Well, they should not require -D, or the trait is useless for metaprogramming. I'll see if this can be worked around.

@jacob-carlborg

This comment has been minimized.

Show comment
Hide comment
@jacob-carlborg

jacob-carlborg May 7, 2014

Contributor

The documentation uses "Ddoc".

Contributor

jacob-carlborg commented May 7, 2014

The documentation uses "Ddoc".

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

WRT worrying about 'ddoc' being a word that's known by many users; I expect that this __traits will likely be wrapped up in a suite of phobos helper's, which may parse and return details like args, return values, etc... Users probably won't come in contact with the __traits directly once it's fleshed out.

Contributor

TurkeyMan commented May 7, 2014

WRT worrying about 'ddoc' being a word that's known by many users; I expect that this __traits will likely be wrapped up in a suite of phobos helper's, which may parse and return details like args, return values, etc... Users probably won't come in contact with the __traits directly once it's fleshed out.

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost May 7, 2014

Apparently the lexer is set up so it completely discards comments when -D is not enabled. This can be worked around by changing this line in module.c:

Parser p(this, buf, buflen, docfile != NULL);

To:

// always lex comments, __traits(comment) might require it
bool doDocComment = true;
Parser p(this, buf, buflen, doDocComment);

The above just forwards this option to the Lexer.

The question is will this slow down compilation? I haven't tested the performance. Either way it's really awkward that you would need to enable -D in order to use a trait, you're essentially writing documentation files to disk even if all you're doing is metaprogramming with a trait.

CC'ing @WalterBright and @9rnsr: Would always lexing ddoc comments introduce a major slowdown in compilation speed? If not then I think we should always lex them, otherwise this trait becomes awkward to use.

ghost commented May 7, 2014

Apparently the lexer is set up so it completely discards comments when -D is not enabled. This can be worked around by changing this line in module.c:

Parser p(this, buf, buflen, docfile != NULL);

To:

// always lex comments, __traits(comment) might require it
bool doDocComment = true;
Parser p(this, buf, buflen, doDocComment);

The above just forwards this option to the Lexer.

The question is will this slow down compilation? I haven't tested the performance. Either way it's really awkward that you would need to enable -D in order to use a trait, you're essentially writing documentation files to disk even if all you're doing is metaprogramming with a trait.

CC'ing @WalterBright and @9rnsr: Would always lexing ddoc comments introduce a major slowdown in compilation speed? If not then I think we should always lex them, otherwise this trait becomes awkward to use.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

True "Ddoc" is in the documentation, but I still suspect more people have seen Ddoc comments than know what they are.

I'm in favor of "documentation", for the reason above, for its use in other languages, and because I'm not sure what the proper CamelCase capitalization of "Ddoc" is. Also, new users looking for the feature might be more likely to search dlang.org for "documentation" than "ddoc".

WRT worrying about 'ddoc' being a word that's known by many users; I expect that this __traits will likely be wrapped up in a suite of phobos helper's, which may parse and return details like args, return values, etc... ie, users probably won't come in contact with the __traits directly once it's fleshed out.

This is true. But the __traits name will probably inform the std.trait name, so we might as well sort it out now.

MasonMcGill commented May 7, 2014

True "Ddoc" is in the documentation, but I still suspect more people have seen Ddoc comments than know what they are.

I'm in favor of "documentation", for the reason above, for its use in other languages, and because I'm not sure what the proper CamelCase capitalization of "Ddoc" is. Also, new users looking for the feature might be more likely to search dlang.org for "documentation" than "ddoc".

WRT worrying about 'ddoc' being a word that's known by many users; I expect that this __traits will likely be wrapped up in a suite of phobos helper's, which may parse and return details like args, return values, etc... ie, users probably won't come in contact with the __traits directly once it's fleshed out.

This is true. But the __traits name will probably inform the std.trait name, so we might as well sort it out now.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

Apparently the lexer is set up so it completely discards comments when -D is not enabled. This can be worked around by changing this line in module.c.

This is great! Hopefully extracting ddoc comments isn't too much overhead.

MasonMcGill commented May 7, 2014

Apparently the lexer is set up so it completely discards comments when -D is not enabled. This can be worked around by changing this line in module.c.

This is great! Hopefully extracting ddoc comments isn't too much overhead.

@alexrp

This comment has been minimized.

Show comment
Hide comment
@alexrp

alexrp May 7, 2014

Member

I disagree with making this trait silently fail for symbols that don't exist. If that's the behavior you want (and I sincerely believe this is the exception, not the rule) you can get it by checking with __traits(compiles, ...) first.

Failing loudly by default in that case also makes sense if we're going to make it so this feature doesn't depend on -D.

Member

alexrp commented May 7, 2014

I disagree with making this trait silently fail for symbols that don't exist. If that's the behavior you want (and I sincerely believe this is the exception, not the rule) you can get it by checking with __traits(compiles, ...) first.

Failing loudly by default in that case also makes sense if we're going to make it so this feature doesn't depend on -D.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

I disagree with making this trait silently fail for symbols that don't exist. If that's the behavior you want (and I sincerely believe this is the exception, not the rule) you can get it by checking with __traits(compiles, ...) first.

This is the behavior I'm most unsure about, as well. Does anyone have a conflicting opinion?

MasonMcGill commented May 7, 2014

I disagree with making this trait silently fail for symbols that don't exist. If that's the behavior you want (and I sincerely believe this is the exception, not the rule) you can get it by checking with __traits(compiles, ...) first.

This is the behavior I'm most unsure about, as well. Does anyone have a conflicting opinion?

@bearophile

This comment has been minimized.

Show comment
Hide comment
@bearophile

bearophile May 7, 2014

It is not intended to be involved in providing application functionality.<

People will use it in all ways possible.

__traits(documentation, expr) or __traits(ddoc, expr) are fine for me. The second is a little shorter, and a little more precise. I'd like this feature to work even when you don't use -D. I suggest to add to the unittest the retrieval of the module ddoc (the one at the top). Automatically stripping the leading newline seems good. I think it's acceptable to return an empty string when there is no ddoc available.

bearophile commented May 7, 2014

It is not intended to be involved in providing application functionality.<

People will use it in all ways possible.

__traits(documentation, expr) or __traits(ddoc, expr) are fine for me. The second is a little shorter, and a little more precise. I'd like this feature to work even when you don't use -D. I suggest to add to the unittest the retrieval of the module ddoc (the one at the top). Automatically stripping the leading newline seems good. I think it's acceptable to return an empty string when there is no ddoc available.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

I agree that it shouldn't silently succeed if the symbol doesn't exist.
If the symbol doesn't exist; error. If the symbol exists but isn't documented; empty string.

Also, strip whitespace from both ends?

Contributor

TurkeyMan commented May 7, 2014

I agree that it shouldn't silently succeed if the symbol doesn't exist.
If the symbol doesn't exist; error. If the symbol exists but isn't documented; empty string.

Also, strip whitespace from both ends?

@@ -312,6 +312,7 @@
{
"name" : "bar",
"kind" : "function",
"comment" : " Documentation test\n",

This comment has been minimized.

@MasonMcGill

MasonMcGill May 7, 2014

This file is the expected output for a JSON emission test. It was changed because DMD no longer ignores documentation comments. Previously, DMD would ignore Ddoc comments unless it was run with "-D".

@MasonMcGill

MasonMcGill May 7, 2014

This file is the expected output for a JSON emission test. It was changed because DMD no longer ignores documentation comments. Previously, DMD would ignore Ddoc comments unless it was run with "-D".

Parser p(this, buf, buflen, docfile != NULL);
// Always lex comments; __traits(documentation, ...) might require it.
bool doDocComment = true;
Parser p(this, buf, buflen, doDocComment);

This comment has been minimized.

@MasonMcGill

MasonMcGill May 7, 2014

This change does not seem to have a measurable effect on compilation speed. Compiling Phobos with and without doc-comment recognition took 7.3 seconds on my machine.

@MasonMcGill

MasonMcGill May 7, 2014

This change does not seem to have a measurable effect on compilation speed. Compiling Phobos with and without doc-comment recognition took 7.3 seconds on my machine.

This comment has been minimized.

@WalterBright

WalterBright May 8, 2014

Member

I object to turning this on by default - it also affects memory consumption, which is currently a significant problem with dmd.

@WalterBright

WalterBright May 8, 2014

Member

I object to turning this on by default - it also affects memory consumption, which is currently a significant problem with dmd.

This comment has been minimized.

@MasonMcGill

MasonMcGill May 8, 2014

What do you think about instead adding a compiler flag to turn "extract ddoc comments" on, without emitting extra files?

@MasonMcGill

MasonMcGill May 8, 2014

What do you think about instead adding a compiler flag to turn "extract ddoc comments" on, without emitting extra files?

This comment has been minimized.

@MasonMcGill

MasonMcGill May 8, 2014

Maybe "dmd -D-", to parallel "dmd -o-"?

@MasonMcGill

MasonMcGill May 8, 2014

Maybe "dmd -D-", to parallel "dmd -o-"?

This comment has been minimized.

@WalterBright

WalterBright Jun 6, 2014

Member

Not sure what you mean - do you mean turn on the __traits(documentation,...) while turning off object file generation?

@WalterBright

WalterBright Jun 6, 2014

Member

Not sure what you mean - do you mean turn on the __traits(documentation,...) while turning off object file generation?

This comment has been minimized.

@MasonMcGill

MasonMcGill Jun 6, 2014

Yes; exactly. This would enable the trait without adding to DMD's memory consumption when it isn't used. However, I admit requiring a compiler flag to use a trait isn't exactly an ideal solution.

@MasonMcGill

MasonMcGill Jun 6, 2014

Yes; exactly. This would enable the trait without adding to DMD's memory consumption when it isn't used. However, I admit requiring a compiler flag to use a trait isn't exactly an ideal solution.

This comment has been minimized.

@jacob-carlborg

jacob-carlborg Jun 6, 2014

Contributor

We already have that for the getUnitTests trait.

@jacob-carlborg

jacob-carlborg Jun 6, 2014

Contributor

We already have that for the getUnitTests trait.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

Update:

  • The trait name is now documentation, not comment.
  • Attempting to retrieve the documentation of an expression that is not a symbol now results in an error.
  • This feature now works even if you don't pass the "-D" flag to DMD (with no measurable performance impact, based on my profiling).
  • More tests have been added (let me know if there's anything I missed!)
  • A pull request documenting this feature on dlang.org is now open: dlang/dlang.org#574.

With respect to preprocessing the doc-comments, I agree that stripping newlines is reasonable, but it seems like a separate issue to me--something that should be done during lexing/parsing, not during compile-time reflection. It's a minor point, but I think the definition of a "Ddoc comment" should be consistent between __traits, JSON output, and the documentation generator. This design is also more efficient and avoids memory leaks (again, possibly a minor point, but probably a good sign).

Maybe someone interested can open a request to change the extraction of Ddoc comments during lexing/parsing?

MasonMcGill commented May 7, 2014

Update:

  • The trait name is now documentation, not comment.
  • Attempting to retrieve the documentation of an expression that is not a symbol now results in an error.
  • This feature now works even if you don't pass the "-D" flag to DMD (with no measurable performance impact, based on my profiling).
  • More tests have been added (let me know if there's anything I missed!)
  • A pull request documenting this feature on dlang.org is now open: dlang/dlang.org#574.

With respect to preprocessing the doc-comments, I agree that stripping newlines is reasonable, but it seems like a separate issue to me--something that should be done during lexing/parsing, not during compile-time reflection. It's a minor point, but I think the definition of a "Ddoc comment" should be consistent between __traits, JSON output, and the documentation generator. This design is also more efficient and avoids memory leaks (again, possibly a minor point, but probably a good sign).

Maybe someone interested can open a request to change the extraction of Ddoc comments during lexing/parsing?

@mihails-strasuns

This comment has been minimized.

Show comment
Hide comment
@mihails-strasuns

mihails-strasuns May 7, 2014

Sorry to be very late to the thread but I must mention that I don't like the very idea of this trait. With it comments stop being comments and can possibly affect program code generation, becoming enum strings in disguise. It sounds like a bad precedent.

mihails-strasuns commented May 7, 2014

Sorry to be very late to the thread but I must mention that I don't like the very idea of this trait. With it comments stop being comments and can possibly affect program code generation, becoming enum strings in disguise. It sounds like a bad precedent.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

It's true, that's a risk... but I think there's also significant value in being able to refer to the docs to produce useful error information, or for exposing docs/api info to editing tools as part of a reflection system.

Contributor

TurkeyMan commented May 7, 2014

It's true, that's a risk... but I think there's also significant value in being able to refer to the docs to produce useful error information, or for exposing docs/api info to editing tools as part of a reflection system.

@mihails-strasuns

This comment has been minimized.

Show comment
Hide comment
@mihails-strasuns

mihails-strasuns May 7, 2014

I'd say it needs to be other way around to make it possible safely, injecting compile-time string constants into comments by their name.

mihails-strasuns commented May 7, 2014

I'd say it needs to be other way around to make it possible safely, injecting compile-time string constants into comments by their name.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

I'm not sure how you mean. Example?

Contributor

TurkeyMan commented May 7, 2014

I'm not sure how you mean. Example?

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

Sorry to be very late to the thread but I must mention that I don't like the very idea of this trait. With it comments stop being comments and can possibly affect program code generation, becoming enum strings in disguise. It sounds like a bad precedent.

I agree that using comments to control execution would be bad; however, D already has similar targets of abuse (any string can be subjected to compile-time transformation followed by mixing-in; identifiers are reflective; operators can be overloaded). I interpreted the presence of such features as part of D's "systems language" philosophy.

Python makes its documentation comments easily available, and that's helped build tools that my colleagues and I use every day (Sphinx, IPython, IDEs). I'd like to use this feature in D for an automatic binding generator that will hopefully be similarly useful.

MasonMcGill commented May 7, 2014

Sorry to be very late to the thread but I must mention that I don't like the very idea of this trait. With it comments stop being comments and can possibly affect program code generation, becoming enum strings in disguise. It sounds like a bad precedent.

I agree that using comments to control execution would be bad; however, D already has similar targets of abuse (any string can be subjected to compile-time transformation followed by mixing-in; identifiers are reflective; operators can be overloaded). I interpreted the presence of such features as part of D's "systems language" philosophy.

Python makes its documentation comments easily available, and that's helped build tools that my colleagues and I use every day (Sphinx, IPython, IDEs). I'd like to use this feature in D for an automatic binding generator that will hopefully be similarly useful.

@mihails-strasuns

This comment has been minimized.

Show comment
Hide comment
@mihails-strasuns

mihails-strasuns May 7, 2014

@TurkeyMan something like this:

/**
    Refers to #(fullyQualifiedName!SomeClass)
 */
void foo() {}

where it will try to interpret comments inside #() as D code during DDOC generation step (and create compile-time errors if symbols is not valid). Reflect on D code from DDOC, not the other way around.

@MasonMcGill
Key difference is that right now you can modify comments without affecting program semantics. It is 100% legal to remove all comments completely - you will still get exactly same binary. All other things you have mentioned never allow such freedom of modification being part of actual program source.

Making comments part of code generation step is not a disaster. But it has a lot of impact on language spec, tooling ecosystem and coding habits. Much more than you could expect from one tiny trait.

Such feature unrestricted will inevitably be abused for some sort of DSL definition. This makes me feel uncomfortablel.

mihails-strasuns commented May 7, 2014

@TurkeyMan something like this:

/**
    Refers to #(fullyQualifiedName!SomeClass)
 */
void foo() {}

where it will try to interpret comments inside #() as D code during DDOC generation step (and create compile-time errors if symbols is not valid). Reflect on D code from DDOC, not the other way around.

@MasonMcGill
Key difference is that right now you can modify comments without affecting program semantics. It is 100% legal to remove all comments completely - you will still get exactly same binary. All other things you have mentioned never allow such freedom of modification being part of actual program source.

Making comments part of code generation step is not a disaster. But it has a lot of impact on language spec, tooling ecosystem and coding habits. Much more than you could expect from one tiny trait.

Such feature unrestricted will inevitably be abused for some sort of DSL definition. This makes me feel uncomfortablel.

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

Making comments part of code generation step is not a disaster. But it has a lot of impact on language spec, tooling ecosystem and coding habits. Much more than you could expect from one tiny trait.

A less restricted version of this feature has existed in Python for years, and the only uses I've seen of it are

  • documentation forwarding (for wrappers, website generators, editors, and interactive interpreters).
  • extracting and running unit tests from doc-comments.

It seems like you condone the former, and there's no motivation to do the latter in D, because D has unittest.

Such feature unrestricted will inevitably be abused for some sort of DSL definition. This makes me feel uncomfortablel.

I haven't seen it used in Python to make DSLs, and Python

  • is more often used for DSL-friendly tasks, like configuration.
  • has a more restricted lambda expression than does D, and has no equivalent to D's lazy, leaving a larger gap for DSLs to fill in Python than in D.

I hear your point, but it seems pretty low-risk to me.

MasonMcGill commented May 7, 2014

Making comments part of code generation step is not a disaster. But it has a lot of impact on language spec, tooling ecosystem and coding habits. Much more than you could expect from one tiny trait.

A less restricted version of this feature has existed in Python for years, and the only uses I've seen of it are

  • documentation forwarding (for wrappers, website generators, editors, and interactive interpreters).
  • extracting and running unit tests from doc-comments.

It seems like you condone the former, and there's no motivation to do the latter in D, because D has unittest.

Such feature unrestricted will inevitably be abused for some sort of DSL definition. This makes me feel uncomfortablel.

I haven't seen it used in Python to make DSLs, and Python

  • is more often used for DSL-friendly tasks, like configuration.
  • has a more restricted lambda expression than does D, and has no equivalent to D's lazy, leaving a larger gap for DSLs to fill in Python than in D.

I hear your point, but it seems pretty low-risk to me.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

There are better tools in D for DSL's. I tend to think the probability of abuse is very low, since there are so many other (better) options to do the sorts of things I can imagine this being abused for.

Contributor

TurkeyMan commented May 7, 2014

There are better tools in D for DSL's. I tend to think the probability of abuse is very low, since there are so many other (better) options to do the sorts of things I can imagine this being abused for.

static assert(!__traits(compiles, __traits(documentation, 3)));
static assert(!__traits(compiles, __traits(documentation, "4")));
}

This comment has been minimized.

@jacob-carlborg

jacob-carlborg May 7, 2014

Contributor

You should check for some symbol that does not have a documentation comment. Probably a symbol with a regular comment as well.

@jacob-carlborg

jacob-carlborg May 7, 2014

Contributor

You should check for some symbol that does not have a documentation comment. Probably a symbol with a regular comment as well.

@9rnsr

This comment has been minimized.

Show comment
Hide comment
@9rnsr

9rnsr May 7, 2014

Member

I cannot see benefit for the processing of ddoc comment during compilation. I think that ddoc comment is meta-information which is higher than the code. I think processing high-level layer information (ddoc comment) in low level layer (CTFE interpretation) is bad information model.

As more essential problem, __traits result is only usable only during CTFE. And, currently CTFE result can be used only for code generation. Therefore, if you want to get a custom web page by using the new __traits , you must generate the code which outputs the required webpage, then run the code to get actual result. It's definitely inefficient.

Member

9rnsr commented May 7, 2014

I cannot see benefit for the processing of ddoc comment during compilation. I think that ddoc comment is meta-information which is higher than the code. I think processing high-level layer information (ddoc comment) in low level layer (CTFE interpretation) is bad information model.

As more essential problem, __traits result is only usable only during CTFE. And, currently CTFE result can be used only for code generation. Therefore, if you want to get a custom web page by using the new __traits , you must generate the code which outputs the required webpage, then run the code to get actual result. It's definitely inefficient.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 7, 2014

Contributor

I often work with systems where you interact with editors and various other tooling, and that tooling benefits significantly from being able to present API information in the editor's GUI.
Compile time reflection is used to provide data via an editor API which the tooling can make use of. Code being able to tell you about itself is the definition of reflection, and I don't see why a line should be drawn at the human readable information when everything else is thoroughly reflected.

To separate this data from the binary is error-prone in my experience, especially when remote debugging (which is standard practise in gamedev) and the filesystem is not present. Without embedding such data in the binary, an exe is represented by a bundle of files including the associated metadata (docs in this case), and losing sync becomes very likely.

I definitely want the reflected documentation embedded in the exe. It simplifies everything.
Currently, I use UDA's to manually tag duplicates of the documentation which is also present in the ddoc header, and I find these duplicate strings often fall out of sync. DRY man ;)
/** blah blah */
@editor(x, y, "blah blah")
void func();

Contributor

TurkeyMan commented May 7, 2014

I often work with systems where you interact with editors and various other tooling, and that tooling benefits significantly from being able to present API information in the editor's GUI.
Compile time reflection is used to provide data via an editor API which the tooling can make use of. Code being able to tell you about itself is the definition of reflection, and I don't see why a line should be drawn at the human readable information when everything else is thoroughly reflected.

To separate this data from the binary is error-prone in my experience, especially when remote debugging (which is standard practise in gamedev) and the filesystem is not present. Without embedding such data in the binary, an exe is represented by a bundle of files including the associated metadata (docs in this case), and losing sync becomes very likely.

I definitely want the reflected documentation embedded in the exe. It simplifies everything.
Currently, I use UDA's to manually tag duplicates of the documentation which is also present in the ddoc header, and I find these duplicate strings often fall out of sync. DRY man ;)
/** blah blah */
@editor(x, y, "blah blah")
void func();

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill May 7, 2014

I cannot see benefit for the processing of ddoc comment during compilation. I think that ddoc comment is meta-information which is higher than the code. I think processing high-level layer information (ddoc comment) in low level layer (CTFE interpretation) is bad information model.

I think you're right when it comes to application or systems programming, but when it comes to library programming, Ddoc notes have become more than comments on the source: they're essentially a user interface. D has already bent over backwards to support interfacing with lower level languages (extern (C), extern (C++), etc.), even though one could argue that ABI directives are "lower than the source". Consider this trait a small feature to improve interfacing with scripting languages, development tools, and human readers.

D currently has every facility necessary for generating foreign language bindings at compile-time, except this. In my domain (academic science), providing a library-based replacement for C++ and SWIG--with no need for Makefiles, configuration files, or manual memory management--could be huge.

I'm developing a system to that end, but currently I'm stuck with a workaround similar to Manu's: using

@("
  This function bakes beans.
")
void bake(Bean b) { /* ... */ }

instead of

/**
 * This function bakes beans.
 */
void bake(Bean b) { /* ... */ }

I opened this pull request because I didn't want to ask my users (who may want to wrap existing code) to do the same.

MasonMcGill commented May 7, 2014

I cannot see benefit for the processing of ddoc comment during compilation. I think that ddoc comment is meta-information which is higher than the code. I think processing high-level layer information (ddoc comment) in low level layer (CTFE interpretation) is bad information model.

I think you're right when it comes to application or systems programming, but when it comes to library programming, Ddoc notes have become more than comments on the source: they're essentially a user interface. D has already bent over backwards to support interfacing with lower level languages (extern (C), extern (C++), etc.), even though one could argue that ABI directives are "lower than the source". Consider this trait a small feature to improve interfacing with scripting languages, development tools, and human readers.

D currently has every facility necessary for generating foreign language bindings at compile-time, except this. In my domain (academic science), providing a library-based replacement for C++ and SWIG--with no need for Makefiles, configuration files, or manual memory management--could be huge.

I'm developing a system to that end, but currently I'm stuck with a workaround similar to Manu's: using

@("
  This function bakes beans.
")
void bake(Bean b) { /* ... */ }

instead of

/**
 * This function bakes beans.
 */
void bake(Bean b) { /* ... */ }

I opened this pull request because I didn't want to ask my users (who may want to wrap existing code) to do the same.

@MasonMcGill MasonMcGill changed the title from Adding support for __traits(comment, ...) to Adding support for __traits(documentation, ...) May 7, 2014

@MartinNowak

This comment has been minimized.

Show comment
Hide comment
@MartinNowak

MartinNowak May 9, 2014

Member

I'm kind of worried about documentation affecting the semantic meaning of a program.

Member

MartinNowak commented May 9, 2014

I'm kind of worried about documentation affecting the semantic meaning of a program.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan May 10, 2014

Contributor

Don't be worried, it's amazing! :)

Contributor

TurkeyMan commented May 10, 2014

Don't be worried, it's amazing! :)

@SFrijters

This comment has been minimized.

Show comment
Hide comment
@SFrijters

SFrijters Jun 26, 2014

This functionality would be quite useful to me; is there any chance this will be ready for the 2.066 release?

SFrijters commented Jun 26, 2014

This functionality would be quite useful to me; is there any chance this will be ready for the 2.066 release?

@MasonMcGill

This comment has been minimized.

Show comment
Hide comment
@MasonMcGill

MasonMcGill Jun 26, 2014

Should I add the compiler flag discussed with @WalterBright and @jacob-carlborg (see file comments)?

MasonMcGill commented Jun 26, 2014

Should I add the compiler flag discussed with @WalterBright and @jacob-carlborg (see file comments)?

@ghost ghost added Enhancement labels Aug 4, 2014

@CyberShadow

This comment has been minimized.

Show comment
Hide comment
@CyberShadow

CyberShadow Aug 5, 2014

Member

This feature would be nice to have. The alternative would be that whenever documentation reflection is required, you are forced to use UDAs for documentation, which is rather ugly, unusable with -D, and doesn't work everywhere (e.g. enum members).

I don't see a problem with documentation comments affecting program behavior. I think this only emphasizes the reasons for which we have regular comments and documentation comments.

Also, I'm very skeptical about the memory usage argument. The ASCII text for all documentation is a drop in the bucket of the current memory consumption needed to compile a program. The entire Phobos source code is 8 MB in total, which is practically nothing compared to how much memory is needed to actually build it.

[Shameless plug] Here is my use case: http://blog.thecybershadow.net/2014/08/05/ae-utils-funopt/

Member

CyberShadow commented Aug 5, 2014

This feature would be nice to have. The alternative would be that whenever documentation reflection is required, you are forced to use UDAs for documentation, which is rather ugly, unusable with -D, and doesn't work everywhere (e.g. enum members).

I don't see a problem with documentation comments affecting program behavior. I think this only emphasizes the reasons for which we have regular comments and documentation comments.

Also, I'm very skeptical about the memory usage argument. The ASCII text for all documentation is a drop in the bucket of the current memory consumption needed to compile a program. The entire Phobos source code is 8 MB in total, which is practically nothing compared to how much memory is needed to actually build it.

[Shameless plug] Here is my use case: http://blog.thecybershadow.net/2014/08/05/ae-utils-funopt/

@MartinNowak

This comment has been minimized.

Show comment
Hide comment
@MartinNowak

MartinNowak Aug 20, 2014

Member

I would certainly agree to this if __traits(documentation, symbol) were only available at runtime (as a string constant). Having it available during compilation means it can affect program execution which goes against normal intuition and complicates any refactoring/language tools.

/// a + b
int foo(int a, int b) { return mixin(__traits(documentation, __FUNCTION__)); }

Unless there are good reasons to allow this, we shouldn't accidentally introduce it.

Member

MartinNowak commented Aug 20, 2014

I would certainly agree to this if __traits(documentation, symbol) were only available at runtime (as a string constant). Having it available during compilation means it can affect program execution which goes against normal intuition and complicates any refactoring/language tools.

/// a + b
int foo(int a, int b) { return mixin(__traits(documentation, __FUNCTION__)); }

Unless there are good reasons to allow this, we shouldn't accidentally introduce it.

@CyberShadow

This comment has been minimized.

Show comment
Hide comment
@CyberShadow

CyberShadow Aug 20, 2014

Member

How would that even work? You can't e.g. enumerate a struct's methods at runtime.

Member

CyberShadow commented Aug 20, 2014

How would that even work? You can't e.g. enumerate a struct's methods at runtime.

@MartinNowak

This comment has been minimized.

Show comment
Hide comment
@MartinNowak

MartinNowak Aug 20, 2014

Member

How would that even work? You can't e.g. enumerate a struct's methods at runtime.

Make __traits(documentation, __FUNCTION__) return a reference to a constant string symbol, so it can't be interpreted at compile time but read at runtime.

Member

MartinNowak commented Aug 20, 2014

How would that even work? You can't e.g. enumerate a struct's methods at runtime.

Make __traits(documentation, __FUNCTION__) return a reference to a constant string symbol, so it can't be interpreted at compile time but read at runtime.

@mihails-strasuns

This comment has been minimized.

Show comment
Hide comment
@mihails-strasuns

mihails-strasuns Aug 20, 2014

Making it runtime string / struct sounds like a good compromise to me.

mihails-strasuns commented Aug 20, 2014

Making it runtime string / struct sounds like a good compromise to me.

@TurkeyMan

This comment has been minimized.

Show comment
Hide comment
@TurkeyMan

TurkeyMan Aug 21, 2014

Contributor

It sounds pretty lame to me. There can be an awful lot of text in the docs, and I don't want my exe bigger by that amount of raw data. It needs to be processable, so I can pick and choose the bits that are relevant.

Like we've said before, there are many much better ways to produce a string literal that may be operated on in D. People aren't going to go around making /** ... */ strings 'because they can', and if they do, why is that your problem? I am confident you're not going to see it become some sort of 'trend' which will get out of control.

The reason I want this is so I can populate separate editor tools with information relating to the objects they are editing. The binary defines the objects, and the properties they have. If you update the binary, typically you have to update the editor. It's a classic problem for decades in my industry, and it's a lame state of affairs.
With this __traits, we could parse the documentation blocks and feed it through the existing editor API to populate the editor UI with useful and correct information that can't drift out of sync with the rest of the toolset.
The key advantage is that, since the state of editor metadata is embedded in the binary itself, it's possible for a single editor instance to edit multiple binaries (a daily routine when dealing with cross-platform code), which has traditionally been a huge pain in the butt.

Currently, we do what I have described by abusing UDA's. We stick editor documentation text in a UDA, and it is almost always an exact duplicate of the ddoc comment.
For things that are exposed to the editor, the documentation is repeated; once for ddoc, and once again pasted in a string in a UDA to be supplied via the editor API to the tools.
This is pretty error prone; nobody is familiar with it yet, highly vulnerable to human error, and if we agree that duplicating code sucks, duplicating comment data sucks even more, because you never get any warning when it goes out of sync...

Contributor

TurkeyMan commented Aug 21, 2014

It sounds pretty lame to me. There can be an awful lot of text in the docs, and I don't want my exe bigger by that amount of raw data. It needs to be processable, so I can pick and choose the bits that are relevant.

Like we've said before, there are many much better ways to produce a string literal that may be operated on in D. People aren't going to go around making /** ... */ strings 'because they can', and if they do, why is that your problem? I am confident you're not going to see it become some sort of 'trend' which will get out of control.

The reason I want this is so I can populate separate editor tools with information relating to the objects they are editing. The binary defines the objects, and the properties they have. If you update the binary, typically you have to update the editor. It's a classic problem for decades in my industry, and it's a lame state of affairs.
With this __traits, we could parse the documentation blocks and feed it through the existing editor API to populate the editor UI with useful and correct information that can't drift out of sync with the rest of the toolset.
The key advantage is that, since the state of editor metadata is embedded in the binary itself, it's possible for a single editor instance to edit multiple binaries (a daily routine when dealing with cross-platform code), which has traditionally been a huge pain in the butt.

Currently, we do what I have described by abusing UDA's. We stick editor documentation text in a UDA, and it is almost always an exact duplicate of the ddoc comment.
For things that are exposed to the editor, the documentation is repeated; once for ddoc, and once again pasted in a string in a UDA to be supplied via the editor API to the tools.
This is pretty error prone; nobody is familiar with it yet, highly vulnerable to human error, and if we agree that duplicating code sucks, duplicating comment data sucks even more, because you never get any warning when it goes out of sync...

@MartinNowak

This comment has been minimized.

Show comment
Hide comment
@MartinNowak

MartinNowak Aug 27, 2014

Member

Well accessing documentation at runtime can also change the program behavior so I withdraw my argument. In any case we should carefully evaluate this solution against alternatives, e.g. dmd's json output or customized ddoc macros.

Member

MartinNowak commented Aug 27, 2014

Well accessing documentation at runtime can also change the program behavior so I withdraw my argument. In any case we should carefully evaluate this solution against alternatives, e.g. dmd's json output or customized ddoc macros.

@mleise

This comment has been minimized.

Show comment
Hide comment
@mleise

mleise Nov 5, 2014

Contributor

In the way the way Ddoc affects a web browser's behavior I think it is a good thing. The program might itself want to add tool tips for any See_Also in the Ddoc. And being a systems language there is a lot of things people can do, but shouldn't, like going around bounds checks with arr.ptr[idx]. Add a comment to the trait's documentation: "Documentation is not code and it is not checked for semantic errors. So use this trait only to format and display documentation and the appropriate other traits to reflect on parameter types and similar in order to build code."

Contributor

mleise commented Nov 5, 2014

In the way the way Ddoc affects a web browser's behavior I think it is a good thing. The program might itself want to add tool tips for any See_Also in the Ddoc. And being a systems language there is a lot of things people can do, but shouldn't, like going around bounds checks with arr.ptr[idx]. Add a comment to the trait's documentation: "Documentation is not code and it is not checked for semantic errors. So use this trait only to format and display documentation and the appropriate other traits to reflect on parameter types and similar in order to build code."

@bearophile

This comment has been minimized.

Show comment
Hide comment
@bearophile

bearophile Nov 5, 2014

@mleise >"Documentation is not code and it is not checked for semantic errors.<

Currently the D compilers thankfully verify the correctness of the arguments of functions inside the function ddoc.

bearophile commented Nov 5, 2014

@mleise >"Documentation is not code and it is not checked for semantic errors.<

Currently the D compilers thankfully verify the correctness of the arguments of functions inside the function ddoc.

@mleise

This comment has been minimized.

Show comment
Hide comment
@mleise

mleise Nov 5, 2014

Contributor

@bearophile It checks that you didn't miss(spell) a name, yes. But we still don't have exception lists on functions that the compiler could compare with Ddoc "Throws:" for example.

Contributor

mleise commented Nov 5, 2014

@bearophile It checks that you didn't miss(spell) a name, yes. But we still don't have exception lists on functions that the compiler could compare with Ddoc "Throws:" for example.

@bearophile

This comment has been minimized.

Show comment
Hide comment
@bearophile

bearophile Nov 6, 2014

@mleise I think probably there's no interest in reintroducing checked exceptions from the window after they were thrown out of the door.

bearophile commented Nov 6, 2014

@mleise I think probably there's no interest in reintroducing checked exceptions from the window after they were thrown out of the door.

@andralex

This comment has been minimized.

Show comment
Hide comment
@andralex

andralex Feb 7, 2015

Member

This has apparently reached an impasse. Should we close in a few days?

Member

andralex commented Feb 7, 2015

This has apparently reached an impasse. Should we close in a few days?

@DmitryOlshansky

This comment has been minimized.

Show comment
Hide comment
@DmitryOlshansky

DmitryOlshansky Jun 26, 2015

Member

Few days struck long ago, just saying...

Member

DmitryOlshansky commented Jun 26, 2015

Few days struck long ago, just saying...

@CyberShadow

This comment has been minimized.

Show comment
Hide comment
@CyberShadow

CyberShadow Jun 26, 2015

Member

Currently, we do what I have described by abusing UDA's. We stick editor documentation text in a UDA, and it is almost always an exact duplicate of the ddoc comment.

I think this is a good argument in favor of this change. Either that, or there should be a way to do the reverse (populate symbol documentation somehow from UDAs).

Member

CyberShadow commented Jun 26, 2015

Currently, we do what I have described by abusing UDA's. We stick editor documentation text in a UDA, and it is almost always an exact duplicate of the ddoc comment.

I think this is a good argument in favor of this change. Either that, or there should be a way to do the reverse (populate symbol documentation somehow from UDAs).

@Kapps

This comment has been minimized.

Show comment
Hide comment
@Kapps

Kapps Jul 2, 2015

Contributor

This is a very useful feature. The editor documentation is likely the most common use case, but it is a very prevalent one. C# has the [Description] attribute, and in practice I've found that it's pretty much always a copy and paste of the documentation, with the result being that I tend to not document the property in order to avoid the duplication.

Yes, it's possible to go out of your way to abuse it in a way that makes no sense, but that's possible with virtually every feature in D. You could inject things FILE or LINE in your code in much the same way to invoke different code depending on the module/line/function/package calling your function. You could even use something like "#line 99999" and invoke special code inside a static if to add members to a struct if LINE is 99999. Many features add potential for abuse like this, and while it is a good thing to avoid, at some point you just have to hope people are sane enough to not abuse them. That being said, I do like the idea of it not being possible to use at compile-time, but it would be nice to select at compile-time (by using the trait) which functions should actually have the documentation text included in the runtime executable.

Contributor

Kapps commented Jul 2, 2015

This is a very useful feature. The editor documentation is likely the most common use case, but it is a very prevalent one. C# has the [Description] attribute, and in practice I've found that it's pretty much always a copy and paste of the documentation, with the result being that I tend to not document the property in order to avoid the duplication.

Yes, it's possible to go out of your way to abuse it in a way that makes no sense, but that's possible with virtually every feature in D. You could inject things FILE or LINE in your code in much the same way to invoke different code depending on the module/line/function/package calling your function. You could even use something like "#line 99999" and invoke special code inside a static if to add members to a struct if LINE is 99999. Many features add potential for abuse like this, and while it is a good thing to avoid, at some point you just have to hope people are sane enough to not abuse them. That being said, I do like the idea of it not being possible to use at compile-time, but it would be nice to select at compile-time (by using the trait) which functions should actually have the documentation text included in the runtime executable.

wilzbach added a commit to wilzbach/dmd that referenced this pull request Jun 8, 2017

wilzbach added a commit to wilzbach/dmd that referenced this pull request Jun 8, 2017

wilzbach added a commit to wilzbach/dmd that referenced this pull request Jun 8, 2017

@wilzbach

This comment has been minimized.

Show comment
Hide comment
@wilzbach

wilzbach Jun 8, 2017

Member

@MasonMcGill and others: I revived this PR at #6872
Feedback on the revival is welcome ;-)

Member

wilzbach commented Jun 8, 2017

@MasonMcGill and others: I revived this PR at #6872
Feedback on the revival is welcome ;-)

@wilzbach wilzbach closed this Jun 8, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment