Re: Descent generated documentation
On 7/9/09 6:44 AM, Ary Borenszweig wrote: Hi all! So... I've been playing around with generating ddocs from Descent. I wanted several things: 1. Each reference to a symbol has a link to it. This applied to field types, functions and methods return types and parameters. 2. Get to know the supertype hierarchy of a given class. 3. Get to know direct subclasses of a given class. 4. Get to know all interfaces a class implements. 6. Show documentation for compile-time code. 7. You didn't see I skipped the number 5 in the list. (a little joke for the last point :-P) I already implemented 1, 2, 3, 4, and 6 is really easy with what I have now (but I don't want to do it now). Before giving comments about the documentation I'll show you, please don't judge colors, appeareance, etc. All of that can be changed. This is just a proof of concept of how I think documentation of APIs should look like. (I have to admit I was inspired, a lot, by Javadoc) Templates don't appear in this documentation because I'm lazy. Also I might have skipped the module documentation (should appear at the top), and enum members. And I don't respect visibility, I show everything. I just want to know opinions about this before continuing working on this, maybe later nobody uses it or find it useful. [1] So... here are the (partial) documentations for phobos and tango. phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/ Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/ (I recommend seeing std.stream in phobos, and tango.io.Buffer to see 1, 2, 3 and 4 in effect). [1] Like... The Tango developers, or phobos team might say Oh, the documentation generation can't be automated in our scripts? We have to open Eclipse for that? I know it's better than ddoc or dil, we just don't care, our build process is important here. Before saying that, remember the end-user of your API doesn't care about your build process, she just want to use your API in the best and fastest possible there is. :-) Very nice. A couple of things I want: Some kind of summary Generated source code like the tango documentation has Show all inherited methods in the subclass, only as links
Re: Descent generated documentation
On Thu, 09 Jul 2009 10:18:37 -0400, Ary Borenszweig a...@esperanto.org.ar wrote: Jacob Carlborg escribió: On 7/9/09 6:44 AM, Ary Borenszweig wrote: Hi all! So... I've been playing around with generating ddocs from Descent. I wanted several things: 1. Each reference to a symbol has a link to it. This applied to field types, functions and methods return types and parameters. 2. Get to know the supertype hierarchy of a given class. 3. Get to know direct subclasses of a given class. 4. Get to know all interfaces a class implements. 6. Show documentation for compile-time code. 7. You didn't see I skipped the number 5 in the list. (a little joke for the last point :-P) I already implemented 1, 2, 3, 4, and 6 is really easy with what I have now (but I don't want to do it now). :O Wow, just wow. I am very impressed, it already looks like something I'd much rather have than the current docs. Looking at the Tango docs, there are a lot of empty/sparse pages, it looks like you aren't capturing struct methods, is that the only reason? Show all inherited methods in the subclass, only as links Good one. This is also done by Javadoc. I'll do it. I'll also provide a link for the method overrided by a method, if any. (again, like in Javadoc) er... please copy base documentation, don't link. You can put inherited from BaseClass.basemethod. Reason being, I want to know how object X behaves, I don't want to have to care where it inherited its guts from, and I also don't want to click 20 times to read all the doc for one object. Looks like I have to try and figure out how to install descent again :) -Steve
Re: Descent generated documentation
On Thu, 09 Jul 2009 14:05:26 -0400, Ary Borenszweig a...@esperanto.org.ar wrote: Note that this is in trunk, not in any release yet. Don't worry, by the time I figure out how to do it, you'll have released it :P -Steve
Re: Descent generated documentation
Ary Borenszweig wrote: phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/ Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/ *drool* I agree about the source code -- it's probably the main reason the Tango docs are so slow and it's useless 95% of the time. Doxygen can optionally generate source code in separate files and have links to it, which might be a good optional feature someday.
Re: Descent generated documentation
On 09.07.2009 16:18, Ary Borenszweig wrote: Jacob Carlborg escribió: Generated source code like the tango documentation has Why would you like to see the source code? I never seen this feature in any other documentation generator. One should not need to see the source code to use the API. If a lot of people request it, I'll do it. But I don't like to break encapsulation, even in documentation! :-P Especially with Tango I've found that it's often easier to figure out what you need to know by reading the code than the docs. Particularly Kris' code for some modules is easier to read than the (current and previous) docs, and in some cases the code will always tell you more than docs can. So it would be nice to have a link to the source. Just a link to the plain text version would be perfect.
Re: Descent generated documentation
torhu escribió: On 09.07.2009 16:18, Ary Borenszweig wrote: Jacob Carlborg escribió: Generated source code like the tango documentation has Why would you like to see the source code? I never seen this feature in any other documentation generator. One should not need to see the source code to use the API. If a lot of people request it, I'll do it. But I don't like to break encapsulation, even in documentation! :-P Especially with Tango I've found that it's often easier to figure out what you need to know by reading the code than the docs. Particularly Kris' code for some modules is easier to read than the (current and previous) docs, and in some cases the code will always tell you more than docs can. So it would be nice to have a link to the source. Just a link to the plain text version would be perfect. Then better docs should be written. :-) Looking at the source code tempts you to do dirty things. I don't want that happenning.
Re: Descent generated documentation
Ary Borenszweig escribió: Hi all! So... I've been playing around with generating ddocs from Descent. phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/ Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/ I've updated the docs. New things: - Visibility is respected - Everything except templates are listed (also nested types are listed) - Modifiers are shown - Public imports are listed (but it doesn't work quite well, I'll check it) - Module level documentation is shown - Inherited methods are shown Still no expand/collapse thingy.
Re: Descent generated documentation
Ary Borenszweig wrote: Ary Borenszweig escribió: Hi all! So... I've been playing around with generating ddocs from Descent. phobos: http://downloads.dsource.org/projects/descent/ddoc/phobos/ Tango: http://downloads.dsource.org/projects/descent/ddoc/tango/ I've updated the docs. New things: - Visibility is respected - Everything except templates are listed (also nested types are listed) - Modifiers are shown - Public imports are listed (but it doesn't work quite well, I'll check it) - Module level documentation is shown - Inherited methods are shown Still no expand/collapse thingy. Regarding visibility, would it be onerous to have a switch somewhere that lets you produce internal documentation that shows private and protected members? But this is quite cool; always nice to have another alternative. :)
