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


 Don't worry, by the time I figure out how to do it, you'll have
 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 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


 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, 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 reply "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


  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
Jul 10 2009
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


  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.
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/


 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...)
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 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 reply "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
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 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