www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Cross-references in generated ddoc

reply Ary Manzana <ary esperanto.org.ar> writes:
Hi all,

I just submitted a pull request that makes ddoc generate 
cross-references... even for templates!

https://github.com/D-Programming-Language/dmd/pull/865

It would be awesome if you can try it with your projects, see if it's 
working properly and doesn't choke. I tried it with phobos and it worked 
fine.

Also, if someone has ideas about how to solve the issues I describe, 
they are more than welcome.
Apr 03 2012
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-04-04 07:38, Ary Manzana wrote:
 Hi all,

 I just submitted a pull request that makes ddoc generate
 cross-references... even for templates!

 https://github.com/D-Programming-Language/dmd/pull/865

 It would be awesome if you can try it with your projects, see if it's
 working properly and doesn't choke. I tried it with phobos and it worked
 fine.

 Also, if someone has ideas about how to solve the issues I describe,
 they are more than welcome.

That's awesome. Looking at http://pancake.io/1e79d0/array.html, none of the templates are cross-referenced, or was that one of the problems? Why are you not using the mangled name when creating anchors? -- /Jacob Carlborg
Apr 04 2012
parent reply Ary Manzana <ary esperanto.org.ar> writes:
On 4/4/12 6:35 PM, Jacob Carlborg wrote:
 On 2012-04-04 07:38, Ary Manzana wrote:
 Hi all,

 I just submitted a pull request that makes ddoc generate
 cross-references... even for templates!

 https://github.com/D-Programming-Language/dmd/pull/865

 It would be awesome if you can try it with your projects, see if it's
 working properly and doesn't choke. I tried it with phobos and it worked
 fine.

 Also, if someone has ideas about how to solve the issues I describe,
 they are more than welcome.

That's awesome. Looking at http://pancake.io/1e79d0/array.html, none of the templates are cross-referenced, or was that one of the problems?

Ah, no. That's because I ran it against object.di, which doesn't have ddoc comments at all. I don't generate cross-references to undocumented symbols. I uploaded a new version which I ran against an object.di which has empty ddocs for everything. Now you can see there are some cross-references. (if you find some is missing, please tell me).
 Why are you not using the mangled name when creating anchors?

I don't think there's need for the mangled name. It's also more natural to give a link like foo.html?Some.Class than a mangled name.
Apr 04 2012
parent reply Jacob Carlborg <doob me.com> writes:
On 2012-04-04 13:38, Ary Manzana wrote:

 Ah, no. That's because I ran it against object.di, which doesn't have
 ddoc comments at all. I don't generate cross-references to undocumented
 symbols.

 I uploaded a new version which I ran against an object.di which has
 empty ddocs for everything. Now you can see there are some
 cross-references. (if you find some is missing, please tell me).

Cool, but what I actually was referring to was template types, i.e. the first declaration in http://pancake.io/1e79d0/array.html: ForeachType!(Range)[] array(Range)(Range r); "ForeachType" is not a link.
 Why are you not using the mangled name when creating anchors?

I don't think there's need for the mangled name. It's also more natural to give a link like foo.html?Some.Class than a mangled name.

Sure but then it won't be possible to reference different overloaded functions? If you're not creating your own human readable form of mangling, i.e. foo.html#Foo.bar(int) foo.html#Foo.bar(char) I think it's more important that the doc generator behaves correctly than outputting pretty URL's. I found a case where the fully qualified name is not used: http://pancake.io/1e79d0/complex.html#toString The name is just "toString" instead of "Complex.toString". BTW, why are adding an empty "a" tag for the anchor? Just add an "id" on the actual tag you want to refer to. The cross-referencing worked better in Descent, why are you doing it differently? -- /Jacob Carlborg
Apr 04 2012
parent reply Ary Manzana <ary esperanto.org.ar> writes:
On 4/4/12 8:05 PM, Jacob Carlborg wrote:
 On 2012-04-04 13:38, Ary Manzana wrote:

 Ah, no. That's because I ran it against object.di, which doesn't have
 ddoc comments at all. I don't generate cross-references to undocumented
 symbols.

 I uploaded a new version which I ran against an object.di which has
 empty ddocs for everything. Now you can see there are some
 cross-references. (if you find some is missing, please tell me).

Cool, but what I actually was referring to was template types, i.e. the first declaration in http://pancake.io/1e79d0/array.html: ForeachType!(Range)[] array(Range)(Range r); "ForeachType" is not a link.

You are right! I was missing doing cross-reference for template instances. Now I did it, but I was actually forgetting to do cross-references for template instances inside templates. :-P So now I did it. Take a look, much better! :-) http://pancake.io/1e79d0/array.html#array
 Why are you not using the mangled name when creating anchors?

I don't think there's need for the mangled name. It's also more natural to give a link like foo.html?Some.Class than a mangled name.

Sure but then it won't be possible to reference different overloaded functions? If you're not creating your own human readable form of mangling, i.e. foo.html#Foo.bar(int) foo.html#Foo.bar(char) I think it's more important that the doc generator behaves correctly than outputting pretty URL's.

But you can't reference a function in the generated ddoc. You could do it manually, but then you'd have to figure out the mangling or something like that. Also, when guessing what an identifier resolves to, I can't possibly know which template parameters to use. Also, all overloads will have more or less the same documentation and they will be one next to the other. I don't think that's an issue for a documentation system.
 I found a case where the fully qualified name is not used:

 http://pancake.io/1e79d0/complex.html#toString

 The name is just "toString" instead of "Complex.toString".

Thanks. I had a problem with template members. It's now fixed. http://pancake.io/1e79d0/complex.html#Complex.toString
 BTW, why are adding an empty "a" tag for the anchor? Just add an "id" on
 the actual tag you want to refer to.

I wanted to do that. But I have to deal with ddoc macros. Every declaration is put inside a <dt> tag. That is issued with a $(DT ...) macro. So I'd have to create another macro, say $DT_WITH_ID or something like that that outputs the id. I can't simply output an id attribute because I'm not generating html: I'm generating ddoc. I mean, what other formats was Walter thinking of? PDF? Just use an HTML to PDF converter. Ummm... plain text? Microsoft Doc? I don't know. Why can't we just generate html and that's it?
 The cross-referencing worked better in Descent, why are you doing it
 differently?

Well, Descent kept a lot of information to be as precise as possible. DMD is not my code so I tried to modify it as least as possible, without adding too much overhead to the code or memory. I just added a member to the TypeIdentifier struct. I would need to change a lot more to make it work as Descent worked... but I think what I did now with DMD is good enough. :-)
Apr 04 2012
next sibling parent reply Ary Manzana <ary esperanto.org.ar> writes:
On 4/4/12 9:53 PM, Ary Manzana wrote:
 On 4/4/12 8:05 PM, Jacob Carlborg wrote:
 On 2012-04-04 13:38, Ary Manzana wrote:

 Ah, no. That's because I ran it against object.di, which doesn't have
 ddoc comments at all. I don't generate cross-references to undocumented
 symbols.

 I uploaded a new version which I ran against an object.di which has
 empty ddocs for everything. Now you can see there are some
 cross-references. (if you find some is missing, please tell me).

Cool, but what I actually was referring to was template types, i.e. the first declaration in http://pancake.io/1e79d0/array.html: ForeachType!(Range)[] array(Range)(Range r); "ForeachType" is not a link.

You are right! I was missing doing cross-reference for template instances. Now I did it, but I was actually forgetting to do cross-references for template instances inside templates. :-P So now I did it. Take a look, much better! :-) http://pancake.io/1e79d0/array.html#array

Whoa! And take a look at this: http://pancake.io/1e79d0/algorithm.html It's all colorful and linky, even for template if conditions! :-D Thanks for catching that, Jacob. By the way, I think a "show source" would be nice to have, like what they have in Ruby... no? It helps you find bugs faster, or understand the code better if the documentation is not precise enough...
Apr 04 2012
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2012-04-04 15:59, Ary Manzana wrote:

 Whoa!

 And take a look at this:

 http://pancake.io/1e79d0/algorithm.html

 It's all colorful and linky, even for template if conditions! :-D

 Thanks for catching that, Jacob.

 By the way, I think a "show source" would be nice to have, like what
 they have in Ruby... no? It helps you find bugs faster, or understand
 the code better if the documentation is not precise enough...

Yeah, that would be great. Both a link that shows the complete source code of the module (we're actually already have this, but it's done manually with a macro) and a "show source" link at each declaration. -- /Jacob Carlborg
Apr 04 2012
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2012-04-04 15:59, Ary Manzana wrote:

 By the way, I think a "show source" would be nice to have, like what
 they have in Ruby... no? It helps you find bugs faster, or understand
 the code better if the documentation is not precise enough...

BTW, I really like the filters in the Ruby documentation: http://www.ruby-doc.org/core-1.9.3/ -- /Jacob Carlborg
Apr 04 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-04-04 15:53, Ary Manzana wrote:

 You are right!

 I was missing doing cross-reference for template instances. Now I did
 it, but I was actually forgetting to do cross-references for template
 instances inside templates. :-P

 So now I did it. Take a look, much better! :-)

 http://pancake.io/1e79d0/array.html#array

Thanks, much better now :)
 But you can't reference a function in the generated ddoc. You could do
 it manually, but then you'd have to figure out the mangling or something
 like that. Also, when guessing what an identifier resolves to, I can't
 possibly know which template parameters to use.

For example, Phobos uses XREF to reference symbols. The template parameter doesn't matter since that will refer to the same function.
 Also, all overloads will have more or less the same documentation and
 they will be one next to the other. I don't think that's an issue for a
 documentation system.

I guess you're right.
 Thanks. I had a problem with template members. It's now fixed.

 http://pancake.io/1e79d0/complex.html#Complex.toString

Good.
 I wanted to do that. But I have to deal with ddoc macros. Every
 declaration is put inside a <dt> tag. That is issued with a $(DT ...)
 macro. So I'd have to create another macro, say $DT_WITH_ID or something
 like that that outputs the id.

 I can't simply output an id attribute because I'm not generating html:
 I'm generating ddoc.

Ok, I see. But why don't you create $DT_WITH_ID then :)
 I mean, what other formats was Walter thinking of? PDF? Just use an HTML
 to PDF converter. Ummm... plain text? Microsoft Doc? I don't know. Why
 can't we just generate html and that's it?

I think the original idea was to be able to directly output PDF or similar but I don't think that turned out so well. Now Walter also says he is way more productive when using ddoc instead of plain HTML. That's why dlang.org is written using ddoc.
 Well, Descent kept a lot of information to be as precise as possible.
 DMD is not my code so I tried to modify it as least as possible, without
 adding too much overhead to the code or memory. I just added a member to
 the TypeIdentifier struct. I would need to change a lot more to make it
 work as Descent worked... but I think what I did now with DMD is good
 enough. :-)

Fair enough. I think it's great what you've done with the doc generator but it can become even better. Like listing methods from base classes, listing inherited classes and implemented interfaces inherit doc comments and so on, just like Descent does. -- /Jacob Carlborg
Apr 04 2012
parent Ary Manzana <ary esperanto.org.ar> writes:
On 4/4/12 11:11 PM, Jacob Carlborg wrote:
 On 2012-04-04 15:53, Ary Manzana wrote:

 You are right!

 I was missing doing cross-reference for template instances. Now I did
 it, but I was actually forgetting to do cross-references for template
 instances inside templates. :-P

 So now I did it. Take a look, much better! :-)

 http://pancake.io/1e79d0/array.html#array

Thanks, much better now :)
 But you can't reference a function in the generated ddoc. You could do
 it manually, but then you'd have to figure out the mangling or something
 like that. Also, when guessing what an identifier resolves to, I can't
 possibly know which template parameters to use.

For example, Phobos uses XREF to reference symbols. The template parameter doesn't matter since that will refer to the same function.
 Also, all overloads will have more or less the same documentation and
 they will be one next to the other. I don't think that's an issue for a
 documentation system.

I guess you're right.
 Thanks. I had a problem with template members. It's now fixed.

 http://pancake.io/1e79d0/complex.html#Complex.toString

Good.
 I wanted to do that. But I have to deal with ddoc macros. Every
 declaration is put inside a <dt> tag. That is issued with a $(DT ...)
 macro. So I'd have to create another macro, say $DT_WITH_ID or something
 like that that outputs the id.

 I can't simply output an id attribute because I'm not generating html:
 I'm generating ddoc.

Ok, I see. But why don't you create $DT_WITH_ID then :)

Yes, I think I will eventually do that, if the pull gets accepted.
Apr 05 2012
prev sibling next sibling parent reply David Gileadi <gileadis NSPMgmail.com> writes:
On 4/3/12 10:38 PM, Ary Manzana wrote:
 Hi all,

 I just submitted a pull request that makes ddoc generate
 cross-references... even for templates!

 https://github.com/D-Programming-Language/dmd/pull/865

 It would be awesome if you can try it with your projects, see if it's
 working properly and doesn't choke. I tried it with phobos and it worked
 fine.

 Also, if someone has ideas about how to solve the issues I describe,
 they are more than welcome.

This looks good. One bug: for http://pancake.io/1e79d0/array.html#insert it appears to have dropped the name/link for which function to use instead.
Apr 04 2012
next sibling parent Ary Manzana <ary esperanto.org.ar> writes:
On 4/4/12 10:00 PM, David Gileadi wrote:
 On 4/3/12 10:38 PM, Ary Manzana wrote:
 Hi all,

 I just submitted a pull request that makes ddoc generate
 cross-references... even for templates!

 https://github.com/D-Programming-Language/dmd/pull/865

 It would be awesome if you can try it with your projects, see if it's
 working properly and doesn't choke. I tried it with phobos and it worked
 fine.

 Also, if someone has ideas about how to solve the issues I describe,
 they are more than welcome.

This looks good. One bug: for http://pancake.io/1e79d0/array.html#insert it appears to have dropped the name/link for which function to use instead.

No, that's not a bug. The ddoc comment is: /++ $(RED Deprecated. It will be removed in May 2012. Please use $(LREF insertInPlace) instead.) Same as $(XREF array, insertInPlace). +/ The problem is, I didn't define the LREF and XREF macros when generating the docs. But when Walter and Andrei generate the docs they use this: https://github.com/D-Programming-Language/d-programming-language.org/blob/master/std.ddoc#L316 If you ask me, that's a bad smell. What if I want to make the docs in my own format? How can I know all the macros to use? Hmmm....
Apr 04 2012
prev sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Wednesday, April 04, 2012 22:15:10 Ary Manzana wrote:
 But when Walter and Andrei generate the docs they use this:
 
 https://github.com/D-Programming-Language/d-programming-language.org/blob/ma
 ster/std.ddoc#L316
 
 If you ask me, that's a bad smell. What if I want to make the docs in my
 own format? How can I know all the macros to use? Hmmm....

ddoc is designed with the idea that you can provide a file with your own macros rather than just having built-in ones (not to mention, then having to build in all macros into the compiler). It would be incredibly limiting. If you want to generate the docs in your own format, then you can provide your own ddoc file which defines the macros how you'd like, but it's very much on purpose that there be a ddoc file. If you had your own project with macros that helped you with your documentation, then anyone wanting to generate the documentation differently is going to need to have their own ddoc file with different versions of those macros. That's expecteed, and I don't see why it would be a code smell. Anything else would be saying that the very idea of user-defined macros is a bad idea, which very much goes against how ddoc works. - Jonathan M Davis
Apr 04 2012
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Wed, 04 Apr 2012 01:38:42 -0400, Ary Manzana <ary esperanto.org.ar>  
wrote:

 Hi all,

 I just submitted a pull request that makes ddoc generate  
 cross-references... even for templates!

 https://github.com/D-Programming-Language/dmd/pull/865

 It would be awesome if you can try it with your projects, see if it's  
 working properly and doesn't choke. I tried it with phobos and it worked  
 fine.

 Also, if someone has ideas about how to solve the issues I describe,  
 they are more than welcome.

Please, Please Walter, include this after 2.059 is released. This is a significant improvement. -Steve
Apr 04 2012
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2012-04-04 07:38, Ary Manzana wrote:
 Hi all,

 I just submitted a pull request that makes ddoc generate
 cross-references... even for templates!

 https://github.com/D-Programming-Language/dmd/pull/865

 It would be awesome if you can try it with your projects, see if it's
 working properly and doesn't choke. I tried it with phobos and it worked
 fine.

 Also, if someone has ideas about how to solve the issues I describe,
 they are more than welcome.

This is maybe asking for a bit too much but, would it be possible to add cross-referencing in the examples? -- /Jacob Carlborg
Apr 04 2012