digitalmars.D.announce - Descent generated documentation
- Ary Borenszweig (34/34) Jul 08 2009 Hi all!
- Lutger (16/16) Jul 08 2009 This is simply the most useful documentation tool for D even if you woul...
- Ary Borenszweig (32/56) Jul 09 2009 Good suggestion.
- Jacob Carlborg (5/40) Jul 09 2009 Very nice. A couple of things I want:
- Ary Borenszweig (12/65) Jul 09 2009 As I answered to Lutger, I'll probably just allow you to expand/collapse...
- Steven Schveighoffer (14/37) Jul 09 2009 :O Wow, just wow.
- Ary Borenszweig (4/48) Jul 09 2009 Yes, I´ll copy the docs from the base classes.
- Steven Schveighoffer (5/6) Jul 09 2009 Don't worry, by the time I figure out how to do it, you'll have released...
- BCS (7/17) Jul 09 2009 The way I do it on windows is quick and dirty:
- torhu (7/14) Jul 09 2009 Especially with Tango I've found that it's often easier to figure out
- Ary Borenszweig (4/22) Jul 09 2009 Then better docs should be written. :-)
- Gide Nwawudu (6/28) Jul 10 2009 It is helpful to read the source code, the unittests are enlightening.
- Ary Borenszweig (7/35) Jul 10 2009 Now that's a good idea!!
- BCS (8/11) Jul 10 2009 /// General usage
- Lutger (1/1) Jul 10 2009 Cool, can you do preconditions and class invariants too?
- Ary Borenszweig (2/3) Jul 10 2009 Sure.
- Steven Schveighoffer (9/30) Jul 10 2009 Having a link to the source code is helpful for clarification, especiall...
- Ary Borenszweig (2/37) Jul 10 2009 Ok, I'll provide an option then.
- Robert Fraser (6/8) Jul 09 2009 *drool*
- Ary Borenszweig (9/15) Jul 09 2009 I've updated the docs. New things:
- Daniel Keep (5/23) Jul 09 2009 Regarding visibility, would it be onerous to have a switch somewhere
- Robert Fraser (3/4) Jul 10 2009 What are the other alternatives? The interlinks are all but necessary
- Daniel Keep (4/9) Jul 10 2009 dmd and kandil. I've used the Tango docs fairly well without the
- Ary Borenszweig (7/30) Jul 10 2009 It already works like that, you can select that in the UI that allows
- torhu (3/7) Jul 10 2009 I'd say the first order is right. package is 'private to the library',
- Daniel Keep (5/14) Jul 10 2009 Actually, a better idea might be to insert Javascript to allow filtering
- Steven Schveighoffer (8/22) Jul 10 2009 /me cleans up pool of drool on desk.
- Robert Fraser (6/36) Jul 10 2009 me too
- Ary Borenszweig (12/50) Jul 10 2009 It's not just bikeshed. It's important how the documentation looks,
- Steven Schveighoffer (19/23) Jul 10 2009 More nitpicks:
- Ary Borenszweig (6/37) Jul 10 2009 I like it with italics afterwards. :)
- Ary Borenszweig (11/17) Jul 11 2009 Who wants to drool? :)
- Lutger (18/18) Jul 11 2009 *drools*
- Nick B (6/20) Jul 11 2009 Is it possible to have a documentation layout page, somewhere, where you...
- Ary Borenszweig (5/22) Jul 11 2009 I already use a stylesheet. It's in stylesheet.css.
- Jacob Carlborg (2/19) Jul 11 2009 Please add some spacing between things, a couple of newlines.
- Ary Borenszweig (16/22) Jul 12 2009 Hi again!
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. :-)
Jul 08 2009
This is simply the most useful documentation tool for D even if you would not improve it's appearance! It's fast, concise and quick to navigate, I like it a lot. Some random remarks: I'd like to see the hierarchy, implemented interfaces and such before class ddoc comments. (because some comments can be long) I assume you plan to do something with visibility? How annoying would it be to show links to all modules that a module publicly imports? That would be useful. Some classes and modules are very big, a (clickable) summary of sorts would be nice. See tango.text.Util for example where this has been done manually for all the function templates. Do you know Natural Docs? It has a pretty good though sometimes a little verbose presentation of generated docs (also does summaries): http://www.naturaldocs.org/documentation/html/files/NaturalDocs-.html Especially the indexing bits are very good.
Jul 08 2009
Lutger escribió:This is simply the most useful documentation tool for D even if you would not improve it's appearance! It's fast, concise and quick to navigate, I like it a lot. Some random remarks: I'd like to see the hierarchy, implemented interfaces and such before class ddoc comments. (because some comments can be long)Good suggestion. (this is like that in Javadoc, I didn't notice)I assume you plan to do something with visibility?Yes. I just coded this very quickly without paying much attention to details. I wanted to see if I could implement the "important" things first: links, hierarchy, subtypes, etc. I think I also missed to list the functions. :-P (I collect them, I just forgot to list them) For visibility, you'll be able to choose the maximum visibility level you want to document. This is useful to generate documentation useful for the writers of the API, to see the organization of the code. I'll also document public symbols even if they don't have ddoc comments. I think that "feature" of ddoc is really annoying, because you'll have to document with empty comment public aliases and the like. If it's public, it should be known.How annoying would it be to show links to all modules that a module publicly imports? That would be useful.Another good suggestion, it can be done.Some classes and modules are very big, a (clickable) summary of sorts would be nice. See tango.text.Util for example where this has been done manually for all the function templates.I can see that summary is in the ddoc of the module. It's not generated by the documentation generator. But a summary of a module is a must. I want this to also look like Javadoc, where first you have "field summary", "constructor summary", etc., with links to their description. This makes it easier to find something very quickly. But... a module is much bigger than a Java class. So maybe I'll import jquery and just show every member collapsed, and then you'll be able to expand it. I see if this doesn't slow a lot the documentation browsing. (I don't think jquery is very heavy-weight, specially since it comes minified, and I've used it and it's fast). Browsing the Tango documentation is kind of slow, it takes like 3 seconds to open a module after I click it, I don't know why. So I want the documentation browsing to be fast.Do you know Natural Docs? It has a pretty good though sometimes a little verbose presentation of generated docs (also does summaries): http://www.naturaldocs.org/documentation/html/files/NaturalDocs-.html Especially the indexing bits are very good.I'll take a look at it and see how can it inspire me. :-) Thanks for the good suggestions, Lutger.
Jul 09 2009
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
Jul 09 2009
Jacob Carlborg escribió:On 7/9/09 6:44 AM, Ary Borenszweig wrote:As I answered to Lutger, I'll probably just allow you to expand/collapse things, and everything will be collapsed by default, so it'll be like a summary.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 summaryGenerated source code like the tango documentation hasWhy 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! :-PShow all inherited methods in the subclass, only as linksGood 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)
Jul 09 2009
On Thu, 09 Jul 2009 10:18:37 -0400, Ary Borenszweig <ary esperanto.org.ar> wrote:Jacob Carlborg escribió::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?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).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 :) -SteveShow all inherited methods in the subclass, only as linksGood 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)
Jul 09 2009
Steven Schveighoffer Wrote:On Thu, 09 Jul 2009 10:18:37 -0400, Ary Borenszweig <ary esperanto.org.ar> wrote::-)Jacob Carlborg escribió::O Wow, just wow.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).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?Yes, I´ll copy the docs from the base classes.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.Show all inherited methods in the subclass, only as linksGood 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)Looks like I have to try and figure out how to install descent again :)Note that this is in trunk, not in any release yet.
Jul 09 2009
On Thu, 09 Jul 2009 14:05:26 -0400, Ary Borenszweig <ary 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
Jul 09 2009
Reply to Steven,On Thu, 09 Jul 2009 14:05:26 -0400, Ary Borenszweig <ary esperanto.org.ar> wrote:The way I do it on windows is quick and dirty: - download "eclipse-cpp-galileo-win32.zip" from the C/C++ section here http://www.eclipse.org/downloads/ - unzip it somewhere - download Descent's .zip file (I can't seem to find it, grrrr) - unzip it on top of the first download - run eclipse.exeNote 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
Jul 09 2009
On 09.07.2009 16:18, Ary Borenszweig wrote:Jacob Carlborg escribió: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.Generated source code like the tango documentation hasWhy 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
Jul 09 2009
torhu escribió:On 09.07.2009 16:18, Ary Borenszweig wrote:Then better docs should be written. :-) Looking at the source code tempts you to do dirty things. I don't want that happenning.Jacob Carlborg escribió: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.Generated source code like the tango documentation hasWhy 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
Jul 09 2009
On Thu, 09 Jul 2009 20:01:02 -0300, Ary Borenszweig <ary esperanto.org.ar> wrote:torhu escribió: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. GideOn 09.07.2009 16:18, Ary Borenszweig wrote:Then better docs should be written. :-) Looking at the source code tempts you to do dirty things. I don't want that happenning.Jacob Carlborg escribió: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.Generated source code like the tango documentation hasWhy 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
Jul 10 2009
Gide Nwawudu escribió:On Thu, 09 Jul 2009 20:01:02 -0300, Ary Borenszweig <ary esperanto.org.ar> wrote: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, grrrrrrrrrr....)torhu escribió: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.On 09.07.2009 16:18, Ary Borenszweig wrote:Then better docs should be written. :-) Looking at the source code tempts you to do dirty things. I don't want that happenning.Jacob Carlborg escribió: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.Generated source code like the tango documentation hasWhy 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
Jul 10 2009
Hello Ary,(unfortunately the listing will be "unit test 1", "unit test 2", etc., because there's no way to name unit tests, grrrrrrrrrr....)/// General usage unittest { ... } /// Multi threaded usage unittest { } . . .
Jul 10 2009
Cool, can you do preconditions and class invariants too?
Jul 10 2009
Lutger wrote:Cool, can you do preconditions and class invariants too?Sure.
Jul 10 2009
On Thu, 09 Jul 2009 19:01:02 -0400, Ary Borenszweig <ary esperanto.org.ar> wrote:torhu escribió: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. -SteveOn 09.07.2009 16:18, Ary Borenszweig wrote:Then better docs should be written. :-) Looking at the source code tempts you to do dirty things. I don't want that happenning.Jacob Carlborg escribió: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.Generated source code like the tango documentation hasWhy 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
Jul 10 2009
Steven Schveighoffer wrote:On Thu, 09 Jul 2009 19:01:02 -0400, Ary Borenszweig <ary esperanto.org.ar> wrote:Ok, I'll provide an option then.torhu escribió: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.On 09.07.2009 16:18, Ary Borenszweig wrote:Then better docs should be written. :-) Looking at the source code tempts you to do dirty things. I don't want that happenning.Jacob Carlborg escribió: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.Generated source code like the tango documentation hasWhy 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
Jul 10 2009
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.
Jul 09 2009
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.
Jul 09 2009
Ary Borenszweig wrote:Ary Borenszweig escribió: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. :)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.
Jul 09 2009
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.
Jul 10 2009
Robert Fraser wrote:Daniel Keep wrote:dmd and kandil. I've used the Tango docs fairly well without the interlinks; it's a pain, yes. Personally, I think DDoc is just plain wrong, but maybe that's just me. :PBut 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.
Jul 10 2009
Daniel Keep escribió:Ary Borenszweig wrote: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...)Ary Borenszweig escribió:Regarding visibility, would it be onerous to have a switch somewhere that lets you produce "internal" documentation that shows private and protected members?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.
Jul 10 2009
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.
Jul 10 2009
torhu wrote:On 10.07.2009 14:41, Ary Borenszweig wrote: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.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.
Jul 10 2009
On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig <ary esperanto.org.ar> wrote:Ary Borenszweig escribió:/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! -SteveHi 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.
Jul 10 2009
Steven Schveighoffer wrote:On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig <ary esperanto.org.ar> wrote: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.Ary Borenszweig escribió:/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! -SteveHi 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.
Jul 10 2009
Robert Fraser wrote:Steven Schveighoffer wrote: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)On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig <ary esperanto.org.ar> wrote: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.Ary Borenszweig escribió:/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! -SteveHi 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.
Jul 10 2009
On Fri, 10 Jul 2009 10:05:38 -0400, Steven Schveighoffer <schveiguy 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
Jul 10 2009
Steven Schveighoffer wrote:On Fri, 10 Jul 2009 10:05:38 -0400, Steven Schveighoffer <schveiguy yahoo.com> wrote:I like it with italics afterwards. :) Yes, I need to fix the duplicated inherited methods.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.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.
Jul 10 2009
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
Jul 11 2009
*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 :)
Jul 11 2009
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 pageIs 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
Jul 11 2009
Nick B escribió:Lutger wrote:I already use a stylesheet. It's in stylesheet.css. I'll tweek the generated html further so it can be more customized. Then I'll upload a zip somewhere so others can make others stylesheets, and we can choose together one that's "best" for general use.*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 pageIs 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.
Jul 11 2009
On 7/11/09 7:05 PM, Ary Borenszweig wrote:Ary Borenszweig escribió:Please add some spacing between things, a couple of newlines.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
Jul 11 2009
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/Hi again! I uploaded two zip files: http://downloads.dsource.org/projects/descent/ddoc/descent_phobos_docs.zip http://downloads.dsource.org/projects/descent/ddoc/descent_tango_docs.zip They include all the docs for both libraries, and also a stylesheet.css file. Also now the generated html is indented and properly "css-classed". (but if you need some modification to the generated html, please tell me.) So you can download that and start playing with the stylesheet to make it look better. You might also want to try to include jquery in one of the generated htmls and then attach handlers to the onload event to add collapsible regions, or anything you'd like. I hope you can come up with a nice one. :) The one that looks better will stay in Descent as the default one.
Jul 12 2009