Another use case for __traits(docComment)

Adam D. Ruppe destructionator at
Tue Nov 12 01:59:55 UTC 2019

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.

More information about the Digitalmars-d mailing list