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/ Who wants to drool? :) I updated the docs once more. *Now hierarchies are also shown for templated classes and interfaces*. See for example tango.util.collection.impl.Collection. I also show templated functions and templated types. I still don't show template parameters correctly, and in templated types you'll see a lot of voids and ints. Don't complain yet about that, I need to fix that. Also are missing all the suggestions other made... And I know a lot of other things are not working ok. You may now just complain about the esthetics or missing funcionality. :-P
Re: Descent generated documentation
*drools* Some more wishes: D2 support? Couple of minor suggestions for the aesthetics (this is a matter of taste too of course): - make the declarations stand out more, bold font or something. - all the non-comments stuff should be in a different, monospace font - parameters names in italic - name of the module as the title of the html page In general, I very much would love to see little javascript if at all, CSS for styling with use of div's (and CSS classes). This so that people could style it themselves easily (and contribute nice sheets?). Oh, is it possible to detect overloads? You could add links to them (like with the class hierarchy) or group them together. Could it be done across modules? Last detail: small message at the bottom saying it was generated with descent at date so and so. Right, I'll stop for now :)
Re: Descent generated documentation
Lutger wrote: *drools* Some more wishes: D2 support? Couple of minor suggestions for the aesthetics (this is a matter of taste too of course): - make the declarations stand out more, bold font or something. - all the non-comments stuff should be in a different, monospace font - parameters names in italic - name of the module as the title of the html page Is it possible to have a documentation layout page, somewhere, where you explain, or list, what fonts are used for what i.e. Parameters names are in italics, etc. thanls Nick_B
Re: Descent generated documentation
On Thu, 09 Jul 2009 20:01:02 -0300, Ary Borenszweig a...@esperanto.org.ar wrote: 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. It is helpful to read the source code, the unittests are enlightening. Unless there is an option to include unittests as example code in the documentation. Gide
Re: Descent generated documentation
Daniel Keep wrote: But this is quite cool; always nice to have another alternative. :) What are the other alternatives? The interlinks are all but necessary for larger/OO projects.
Re: Descent generated documentation
Gide Nwawudu escribió: On Thu, 09 Jul 2009 20:01:02 -0300, Ary Borenszweig a...@esperanto.org.ar wrote: 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. It is helpful to read the source code, the unittests are enlightening. Unless there is an option to include unittests as example code in the documentation. Now that's a good idea!! A lot of times unit tests show how an API is supposed to be used, and explains a lot more than documentation. I'll definitely include unit tests in the documentation. (unfortunately the listing will be unit test 1, unit test 2, etc., because there's no way to name unit tests, grr)
Re: Descent generated documentation
Daniel Keep escribió: 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? It already works like that, you can select that in the UI that allows you to generate the documentation. :-) You can select the maximum visibility: private, protected or public. (in the original UI in the plugin for Java there's also package, but... where does package fall? private package protected? protected package public? I think neither, mmm...)
Re: Descent generated documentation
On Thu, 09 Jul 2009 19:01:02 -0400, Ary Borenszweig a...@esperanto.org.ar wrote: 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. Having a link to the source code is helpful for clarification, especially when you didn't write the documentation. Not all developers have teams of people writing comprehensive documentation like Microsoft or Sun :) Most tools have the ability to generate source files in HTML, including javadoc and doxygen. Not doing it by default is fine, but don't assume it's a worthless option. -Steve
Re: Descent generated documentation
On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig a...@esperanto.org.ar 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. /me cleans up pool of drool on desk. One preference, if it's possible, is to copy the description of inherited methods from the base class. Even if not the entire documentation, just a summary, first sentence from the documentation. Already it's better than ddoc. Nice work! -Steve
Re: Descent generated documentation
Steven Schveighoffer wrote: On Thu, 09 Jul 2009 19:01:02 -0400, Ary Borenszweig a...@esperanto.org.ar wrote: 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. Having a link to the source code is helpful for clarification, especially when you didn't write the documentation. Not all developers have teams of people writing comprehensive documentation like Microsoft or Sun :) Most tools have the ability to generate source files in HTML, including javadoc and doxygen. Not doing it by default is fine, but don't assume it's a worthless option. Ok, I'll provide an option then.
Re: Descent generated documentation
On 10.07.2009 14:41, Ary Borenszweig wrote: You can select the maximum visibility: private, protected or public. (in the original UI in the plugin for Java there's also package, but... where does package fall? private package protected? protected package public? I think neither, mmm...) I'd say the first order is right. package is 'private to the library', but protected is available in subclasses everywhere.
Re: Descent generated documentation
Cool, can you do preconditions and class invariants too?
Re: Descent generated documentation
Lutger wrote: Cool, can you do preconditions and class invariants too? Sure.
Re: Descent generated documentation
Robert Fraser wrote: Steven Schveighoffer wrote: On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig a...@esperanto.org.ar 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. /me cleans up pool of drool on desk. One preference, if it's possible, is to copy the description of inherited methods from the base class. Even if not the entire documentation, just a summary, first sentence from the documentation. Already it's better than ddoc. Nice work! -Steve me too Also, I think Javadoc's tables are easier to read. The list view of this looks better, but it's difficult to differentiate what is what. Javadoc's tables lines give a clear separation between sections. Just my bikeshed. It's not just bikeshed. It's important how the documentation looks, because you really just look at documentation and navigate it, nothing else. :) I also though about the tables... but in Javadoc it's easier because each page lists all of the relevant information for a class, interface or enum. Here I have to list all the information for the modules. I could probably do some big sections, and then in each of them tables. Mmm... I'll see how it looks. (tables are nice in Javadoc because you can scroll your eyes down and see the list of things, but in the current list of my docs you have the return type before it, and sometimes modifiers)
Re: Descent generated documentation
On Fri, 10 Jul 2009 10:05:38 -0400, Steven Schveighoffer schvei...@yahoo.com wrote: One preference, if it's possible, is to copy the description of inherited methods from the base class. Even if not the entire documentation, just a summary, first sentence from the documentation. Already it's better than ddoc. Nice work! More nitpicks: You specify where a method is inherited from multiple times, i.e. tango.io.FileConduit inherits close from DeviceConduit, Conduit, and IConduit. And methods overridden still list those methods as inherited. 1. Abstract methods aren't Inherited, they are implemented, so abstract and interface methods shouldn't be listed as inherited methods. 2. Overridden methods aren't inherited, they are overridden, those should be listed differently. All that would be easier, if all methods were listed inline with the appropriate attributions afterwards. i.e.: (/italics/) void close() /inherited from DeviceConduit/ uint write(void[] buf) /overrides DeviceConduit.write, implements OutputStream.write/ You must have expected this firestorm of requests :) People have been complaining about the deficiencies of ddoc for a long time, but nobody's every really improved it. -Steve
Re: Descent generated documentation
Steven Schveighoffer wrote: On Fri, 10 Jul 2009 10:05:38 -0400, Steven Schveighoffer schvei...@yahoo.com wrote: One preference, if it's possible, is to copy the description of inherited methods from the base class. Even if not the entire documentation, just a summary, first sentence from the documentation. Already it's better than ddoc. Nice work! More nitpicks: You specify where a method is inherited from multiple times, i.e. tango.io.FileConduit inherits close from DeviceConduit, Conduit, and IConduit. And methods overridden still list those methods as inherited. 1. Abstract methods aren't Inherited, they are implemented, so abstract and interface methods shouldn't be listed as inherited methods. 2. Overridden methods aren't inherited, they are overridden, those should be listed differently. All that would be easier, if all methods were listed inline with the appropriate attributions afterwards. i.e.: (/italics/) void close() /inherited from DeviceConduit/ uint write(void[] buf) /overrides DeviceConduit.write, implements OutputStream.write/ I like it with italics afterwards. :) Yes, I need to fix the duplicated inherited methods. You must have expected this firestorm of requests :) People have been complaining about the deficiencies of ddoc for a long time, but nobody's every really improved it. But that's what this thread is about! I want comments about how documentation should be presented, and I already received a lot of good suggestions.
Re: Descent generated documentation
torhu wrote: On 10.07.2009 14:41, Ary Borenszweig wrote: You can select the maximum visibility: private, protected or public. (in the original UI in the plugin for Java there's also package, but... where does package fall? private package protected? protected package public? I think neither, mmm...) I'd say the first order is right. package is 'private to the library', but protected is available in subclasses everywhere. Actually, a better idea might be to insert Javascript to allow filtering visibility. Just calling a library? Default to showing only public members. Want to subclass something? Switch to show protected. Doing development on it? Switch to show package/all.
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. :)
