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
parent reply 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
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