Writing code to wrap some Phobos functions for a script language and need documentation to be displayed at runtime...

Would be really nice to just say if(other_docs.length == 0) return __traits(docComment, item).

A UDA can populate other_docs in some functions, but when wrapping libraries you can't add that. Having the doc comment available through reflection means we can reuse these existing items.

On Friday, 8 November 2019 at 14:00:03 UTC, Adam D. Ruppe wrote:
> Writing code to wrap some Phobos functions for a script language and need documentation to be displayed at runtime...
>
> Would be really nice to just say if(other_docs.length == 0) return __traits(docComment, item).
>
> A UDA can populate other_docs in some functions, but when wrapping libraries you can't add that. Having the doc comment available through reflection means we can reuse these existing items.

Yes, please!!

On 11/8/19 9:00 AM, Adam D. Ruppe wrote:
> Writing code to wrap some Phobos functions for a script language and need documentation to be displayed at runtime...
> 
> Would be really nice to just say if(other_docs.length == 0) return __traits(docComment, item).
> 
> A UDA can populate other_docs in some functions, but when wrapping libraries you can't add that. Having the doc comment available through reflection means we can reuse these existing items.

I still am very VERY leery of having anything in comments affect the code in any way.

What about a compromise? Provide access to the docs but ONLY at runtime. That is, you will not know anything about the string at compiletime, just at runtime, and you can make your decisions there.

Should work for your use case.

-Steve

On Monday, 11 November 2019 at 17:16:20 UTC, Steven Schveighoffer wrote:
> I still am very VERY leery of having anything in comments affect the code in any way.

then just.... don't do that.

And btw for the record you could have comments affect code right now:

mixin((__LINE__ % 3) ? "one thing" : "other thing"); // adding a comment above would change the line number and possibly trigger the other thing!


but such a thing is obviously absurd and nobody would write that, unless maybe doing an obfuscated contest.

The same thing is true of documentation comments. You *could* abuse... but why would you? UDAs are easier to use for other purposes anyway. (just right now we are using UDAs for docs just because it is needed elsewhere!)

> What about a compromise? Provide access to the docs but ONLY at runtime. That is, you will not know anything about the string at compiletime, just at runtime, and you can make your decisions there.

Yeah, that'd work for this case but it is a pointless restriction.

On 11/11/19 12:54 PM, Adam D. Ruppe wrote:
> On Monday, 11 November 2019 at 17:16:20 UTC, Steven Schveighoffer wrote:
>> I still am very VERY leery of having anything in comments affect the code in any way.
> 
> then just.... don't do that.
> 
> And btw for the record you could have comments affect code right now:
> 
> mixin((__LINE__ % 3) ? "one thing" : "other thing"); // adding a comment above would change the line number and possibly trigger the other thing!

Haha, yeah, that is what I don't want.

But I think we can safely say that using comments to affect code can result in reasonable looking things (the above is NOT reasonable) that can be exploited by adjusting the comments.

Certainly, it could be allowed at compile-time and just be a guideline not to write code that cares about the data. But we all know that it will happen.

For instance, I like how documented unit tests simply turns the unittest into a ddoc, instead of making ddoc turn into a unit test (which likely could have been the solution if __traits(docComment) were available back then). It's the correct translation, because code can always be turned into comments, but the other way around is questionable.

> The same thing is true of documentation comments. You *could* abuse... but why would you? UDAs are easier to use for other purposes anyway. (just right now we are using UDAs for docs just because it is needed elsewhere!)

One thing that's different from __LINE__ is that __LINE__ is only provided to that line of code. It's not accessible outside the line. __traits(docComment, x) would provide access to the comments from elsewhere. So it may be external abuse that happens.

> 
>> What about a compromise? Provide access to the docs but ONLY at runtime. That is, you will not know anything about the string at compiletime, just at runtime, and you can make your decisions there.
> 
> Yeah, that'd work for this case but it is a pointless restriction.

It would be something that could potentially be expanded later if needed. It's easier to let the toothpaste out of the tube slowly than try to put some of it back in.

-Steve

On Monday, 11 November 2019 at 17:54:07 UTC, Adam D. Ruppe wrote:
> On Monday, 11 November 2019 at 17:16:20 UTC, Steven Schveighoffer wrote:
>> I still am very VERY leery of having anything in comments affect the code in any way.
>
> then just.... don't do that.

That won't stop other people.

> And btw for the record you could have comments affect code right now:
>
> mixin((__LINE__ % 3) ? "one thing" : "other thing"); // adding a comment above would change the line number and possibly trigger the other thing!
>
>
> but such a thing is obviously absurd and nobody would write that, unless maybe doing an obfuscated contest.

That isn't really all that useful. That line of code's only purpose is to be misused and cause misunderstanding.

Someone might come around and say, why modify documentation and code? Why not just modify documentation and then have the code read from that documentation and change behavior instead. That way you keep documentation and implementation in sync!

Kind of odd you have a 1:1 mapping for a scripting language anyways. That doesn't seem like a very rare occurrence. You don't pass any extra meta data for your implementations? They all have 1:1 mapping for types? You implement things like pointers in your scripting language?

On Monday, 11 November 2019 at 20:15:56 UTC, Steven Schveighoffer wrote:
> Certainly, it could be allowed at compile-time and just be a guideline not to write code that cares about the data. But we all know that it will happen.

Indeed, I have seen a lot of trash D code out there.

But I don't want to remove useful features because of it.

> For instance, I like how documented unit tests simply turns the unittest into a ddoc, instead of making ddoc turn into a unit test (which likely could have been the solution if __traits(docComment) were available back then).

I actually doubt that would have been used because that needs significant progressing anyway. What we did use before the unittest thing was just extract the code from the generated HTML documentation which is pretty easy too.

(that's probably what I'll do with my program here, just dump the comments to a separate file and then `import` it to populate the map. but so much more complicated and fragile than just pulling the comment off while reflecting anyway)

> It would be something that could potentially be expanded later if needed. It's easier to let the toothpaste out of the tube slowly than try to put some of it back in.

true. like I'd rather have it just for runtime processing than not at all, but it is still just bleh.

On Tuesday, 12 November 2019 at 01:22:09 UTC, Exil wrote:
> Someone might come around and say, why modify documentation and code? Why not just modify documentation and then have the code read from that documentation and change behavior instead. That way you keep documentation and implementation in sync!

Heh, that might actually be kinda interesting.

But you can already do that kind of thing, just with slightly different syntax. You can put that in a UDA and process it with reflection at CT and embed it into documentation through the UDA too. (my doc generator supports pulling in UDAs to work around the lack of ddoc in reflection; I had to move docs to a UDA and now they're combined anyway, it is just hideous and not as compatible with third party things)

> You don't pass any extra meta data for your implementations?

It depends, but a lot of libraries actually do just work with the script languages and it is nice to just do, for example `script.parseHTML = (string html) => new Document(html);` and then much of the Document object is now available to the script!

But since the Document library is written with ddoc, it is impossible for me to bring in those docs (without an external map generator and loader) for the interactive script.

$ var document = parseHTML(....);
$ \help document.querySelector

no help tho ddoc is present and the method is available to the script :(


I also do a web interface generator. You give it a class, it wraps it up in HTML forms, etc. It would be nice if it gave you the documentation... but it can't even tell if it is there. Best it can do is blindly link to my documentation website and *hope* it is there. (which actually isn't bad, but again it would be cool if it were more fully integrated)

Or use a UDA, since these wrappers don't go as deep as automatically as the script language, so it isn't too bad either, it would just be nice if the ddoc worked.

On Tuesday, 12 November 2019 at 01:59:55 UTC, Adam D. Ruppe wrote:
> On Tuesday, 12 November 2019 at 01:22:09 UTC, Exil wrote:
>> Someone might come around and say, why modify documentation and code? Why not just modify documentation and then have the code read from that documentation and change behavior instead. That way you keep documentation and implementation in sync!
>
> Heh, that might actually be kinda interesting.
>
> But you can already do that kind of thing, just with slightly different syntax. You can put that in a UDA and process it with reflection at CT and embed it into documentation through the UDA too. (my doc generator supports pulling in UDAs to work around the lack of ddoc in reflection; I had to move docs to a UDA and now they're combined anyway, it is just hideous and not as compatible with third party things)

This is also my view. D already supports things that are this messy or more. All this restriction does is lock the barn after the horse has bolted.

You can already do the same degree of mess. You just have to make it ugly. All this restriction does is make good, useful code worse for little benefit.

On 11/12/19 1:32 AM, FeepingCreature wrote:
> On Tuesday, 12 November 2019 at 01:59:55 UTC, Adam D. Ruppe wrote:
>> On Tuesday, 12 November 2019 at 01:22:09 UTC, Exil wrote:
>>> Someone might come around and say, why modify documentation and code? Why not just modify documentation and then have the code read from that documentation and change behavior instead. That way you keep documentation and implementation in sync!
>>
>> Heh, that might actually be kinda interesting.
>>
>> But you can already do that kind of thing, just with slightly different syntax. You can put that in a UDA and process it with reflection at CT and embed it into documentation through the UDA too. (my doc generator supports pulling in UDAs to work around the lack of ddoc in reflection; I had to move docs to a UDA and now they're combined anyway, it is just hideous and not as compatible with third party things)
> 
> This is also my view. D already supports things that are this messy or more. All this restriction does is lock the barn after the horse has bolted.
> 
> You can already do the same degree of mess. You just have to make it ugly. All this restriction does is make good, useful code worse for little benefit.

Breaking the fundamental rule of "this is a comment, it doesn't affect code" that we all learn on day 1 of programming needs a very very compelling use case. I haven't seen it yet.

Alternatively, we could use something other than comments for documentation. e.g.:

@ddoc {
.... // documentation
}

-Steve