www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - Descent generated documentation

reply Ary Borenszweig <ary esperanto.org.ar> writes:
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
next sibling parent reply Lutger <lutger.blijdestijn gmail.com> writes:
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
parent Ary Borenszweig <ary esperanto.org.ar> writes:
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
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
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
next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
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).

 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

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.
 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
 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)
Jul 09 2009
next sibling parent Ary Borenszweig <ary esperanto.org.ar> writes:
Steven Schveighoffer Wrote:

 On Thu, 09 Jul 2009 10:18:37 -0400, Ary Borenszweig <ary 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.

Yes, I´ll copy the docs from the base classes.
 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
prev sibling parent reply torhu <no spam.invalid> writes:
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.
Jul 09 2009
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
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.
Jul 09 2009
next sibling parent reply Gide Nwawudu <gide btinternet.com> writes:
On Thu, 09 Jul 2009 20:01:02 -0300, Ary Borenszweig
<ary 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
Jul 10 2009
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
Gide Nwawudu escribió:
 On Thu, 09 Jul 2009 20:01:02 -0300, Ary Borenszweig
 <ary 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

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

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.

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, grrrrrrrrrr....)
Jul 10 2009
next sibling parent BCS <none anon.com> writes:
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
prev sibling parent reply Lutger <lutger.blijdestijn gmail.com> writes:
Cool, can you do preconditions and class invariants too?
Jul 10 2009
parent Ary Borenszweig <ary esperanto.org.ar> writes:
Lutger wrote:
 Cool, can you do preconditions and class invariants too?

Sure.
Jul 10 2009
prev sibling parent Ary Borenszweig <ary esperanto.org.ar> writes:
Steven Schveighoffer wrote:
 On Thu, 09 Jul 2009 19:01:02 -0400, Ary Borenszweig 
 <ary 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

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.
Jul 10 2009
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Thu, 09 Jul 2009 10:18:37 -0400, Ary Borenszweig <ary 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
Jul 09 2009
prev sibling next sibling parent reply "Steven Schveighoffer" <schveiguy yahoo.com> writes:
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
parent BCS <ao pathlink.com> writes:
Reply to Steven,

 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.
 

released it :P -Steve

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.exe
Jul 09 2009
prev sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Thu, 09 Jul 2009 19:01:02 -0400, Ary Borenszweig <ary 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

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
Jul 10 2009
prev sibling next sibling parent Robert Fraser <fraserofthenight gmail.com> writes:
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
prev sibling next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
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
next sibling parent reply Daniel Keep <daniel.keep.lists gmail.com> writes:
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. :)
Jul 09 2009
next sibling parent reply Robert Fraser <fraserofthenight gmail.com> writes:
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
parent Daniel Keep <daniel.keep.lists gmail.com> writes:
Robert Fraser wrote:
 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.

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. :P
Jul 10 2009
prev sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
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/

- 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...)
Jul 10 2009
parent reply torhu <no spam.invalid> writes:
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
parent Daniel Keep <daniel.keep.lists gmail.com> writes:
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.
Jul 10 2009
prev sibling next sibling parent reply "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig <ary 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
Jul 10 2009
next sibling parent reply Robert Fraser <fraserofthenight gmail.com> writes:
Steven Schveighoffer wrote:
 On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig 
 <ary 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.
Jul 10 2009
parent Ary Borenszweig <ary esperanto.org.ar> writes:
Robert Fraser wrote:
 Steven Schveighoffer wrote:
 On Fri, 10 Jul 2009 01:17:29 -0400, Ary Borenszweig 
 <ary 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)
Jul 10 2009
prev sibling parent Ary Borenszweig <ary esperanto.org.ar> writes:
Steven Schveighoffer wrote:
 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/

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.
Jul 10 2009
prev sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
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
prev sibling next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
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
next sibling parent reply Lutger <lutger.blijdestijn gmail.com> writes:
*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
parent reply Nick B <nick.barbalich gmail.com> writes:
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
Jul 11 2009
parent Ary Borenszweig <ary esperanto.org.ar> writes:
Nick B escribió:
 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.

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.
Jul 11 2009
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 7/11/09 7:05 PM, 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/

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

Please add some spacing between things, a couple of newlines.
Jul 11 2009
prev sibling parent Ary Borenszweig <ary esperanto.org.ar> writes:
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