Hi All,
next round of doc comments. ;) Hope fully getting close to being done.
On Tue, 2006-08-29 at 08:44 +0200, Haykel BEN JEMIA wrote:
> > - I've thought about the best place to document the member vars.
> They
> > don't have a natural representation in the source file, so it's
> either
> > an unnatural one, or the header. I picked the beginning of the .cpp
> > file.
> >
>
> Why not use the header file? To have the definintion and documentation
> of member vars in different files makes it harder to hold them in sync
> (remember to document new vars and to remove the documentation of
> removed ones). This can lead to inconsistent documentation.
I was a little undecided on this one. This also gets back to Allen's
comment about having the class/member doc in the header.
I would like to keep the headers as short and concise as possible. I'm
already slightly annoyed by the license block at the beginning of the
file (we might want to consider shortening it). If I look into the
source I want to get to the meat as quickly as possible. Assuming we
have adequate documentation, if you're looking at the source and you
don't know what you're looking for, you're in the wrong place. For that
to work we need to feature the documentation very prominently, so that
people go there first, before going into the source (which we probably
want to do anyway, after spending the effort necessary to make it
good! ;).
For the member vars I can see it to enforce the closeness of
documentation and documented object, and because we don't have a lot of
member vars normally anyway I was undecided and could go either way. For
the methods that doesn't really apply, as if you change something in the
header you also have to change the implementation, and that is where the
actually interesting changes happen anyway, so having the documentation
there IMHO makes more sense.
But class docs can get pretty long (especially adding explanations like
the DistanceLOD example that Allen mentioned before, with picture etc.).
I don't think it makes sense to have a page or so of documentation at
the beginning of a header file. I can see it at the beginning of the
source file, as that is not used for reference as much.
Another aspect of this is the question of where to put the bulk of the
documentation: class docs or Related Pages? My initial idea was for the
Related Pages to be/become an independently readable documentation
(maybe turn it into a book or reference guide at some point). If that's
the idea, the class doc would be very short and mainly reference the RP.
But then it probably won't be too useful anyway, and could go into
the .cpp file.
> It is also possible to use the doxygen "\copydoc" command to merge the
> documentation of related pages into one page (the main page?). (I know
> the question was asked before, but I didn't come to answer it before,
> sorry ;) )
OK, I wasn't aware of that command. That might come in handy at some
point. ;) For the RP I don't think we need it, the LaTeX output collates
them nicely and in HTML I'd prefer separate pages over a monster page
most of the time anyway. Hm, maybe for searching it might be useful to
have it.
> We seem to have the same taste regarding documentation ;) I think this
> is a MUST and doxygen makes it easy to add links (sometimes too easy,
> i.e. too many links to the Node documentation in Dirk's version, only
> because the word Node is very common)!
Yeah, the Node links are a little exaggerated. ;)
> > - I think one of my informal rules would be: if it is one or two
> clicks
> > away, don't repeat it (e.g. docs for reimplemented classes,
> docs/links
> > for concepts are explained/linked elsewhere). I think it's not too
> much
> > of a burden to click on a link to find a link to the explanation.
> > According to that rule I wouldn't have the Multi-Thread Safety link
> in
> > changed(), because it can be found in beginEditCP(). I might be a
> little
> > more lenient with links (i.e. repeating direct links to the related
> page
> > would be ok), but I would like to avoid repeating actual text as far
> as
> > possible, to simplify changes.
>
> Here also we could use "\copydoc" to copy documentation of other
> members, functions etc. For example take the Node's destructor in
> Dirk's documentation: it's general enough to be used for all field
> containers. It can also be used to extend the documentation of
> inherited members without having to rewrite everything.
I would have to rethink some of the structure using that. The limit is
that it copies the whole think, which might be a little too much. In
general I think the option to copy the documentation for overriden
methods/classes automatically should take care of most things that we
want.
On Tue, 2006-08-29 at 13:06 +0200, jan p. springer wrote:
>
> one possible solution is to split into several doxygen runs. for
> avango the
> (outdated) result is here:
>
> http://www.avango.org/documentation/doxygen/index.html
>
> we defined dependencies for plugins to system libs and have make the
> parallelization for us, eg.
...
>
OK, that's an idea. I assume you're using tag files and doxygen's
external documentation option? One thing that you definitely lose (which
may or may not be a bad thing for a large system) is the completeness of
the Inheritance diagram (e.g. fpFieldContainer), not sure what else you
lose.
But in general that's an interesting idea. We could probably create the
dependencies from the build system automatically (I hate stuff that
needs manual updates).
> we also distinguish between container doc (what an application writer
> needs
> to know, eg. fields), inclusion doc (what someone needs to know when
> extending
> classes, eg. virtual, access rights), and source doc (ie. everything).
We have some of that in OpenSG, but the differences seemed to be very
minimal, so we haven't been using it very actively. How much difference
did that make for you, how useful is it?
On Tue, 2006-08-29 at 07:51 -0500, Allen Bierbaum wrote:
>
> The WikiInclude macro handles it. See:
> http://opensg.vrsource.org/trac/wiki/Test/IncludeMaster
> for an example of it in use.
OK.
> >In a very simple manner (or a very painful one ;). For that to be
> useful
> >we should probably add an even higher level than the SSM, to make the
> >example code really minimal.
> >
> >
> If you think so, that would be fine. As it stands right now I think
> the
> tutorials that use SSM are pretty good and that the SSM does get most
> of
> the internal details out of the way.
True. But doxygen's example handling only let's you include the full
file, and for that even the Tutorial examples are pretty long.
> I tend to think any example should probably be coded in a way (ie.
> using
> tools) that you would want users to actually use in their
> applications.
> People are going to copy the examples as a way to start their
> applications so we might as well give them a good starting point from
> the beginning.
If the example looks like this:
#include <OpenSG/OSGExample.h>
#include <OpenSG/OSGDistanceLod.h>
NodePtr example(void)
{
... // Create example graph
}
int main(int argc, char *argv[])
{
OSG::runExample(argc, argv, example);
}
I don't think anybody will be expecting that to be the framework for an
application. ;)
We probably need a few versions of this for different things, and I
would make the code that is behind OSG::runExample very visible as a
template.
I'm a little torn about replacing the SSM with this. It would be more
limited than even the SSM, but it might encourage people to cut-n-paste
the actual code behind it as a start for their apps, and not hide the
stuff that really happens. In addition to that I would like a more
powerful example application that can be used as the basis of an app and
still be updated/extended by us easily, to add new features (new
navigators etc.). I haven't thought about this a whole lot, but I'm
somewhat agreeing with Marcus that the SSM might not be the best
abstraction layer.
> very brave.
Nah, I just didn't want to look at documentation any more and do some
code instead. It was a Saturday indulgence. ;)
> >Does Trac support that? I couldn't find anything. There is a patch to
> >notify the owner, but how do you add a CC: to every ticket?
> >
> Yes, I will setup trac to do it if you setup a mailing list to send
> the
> e-mails to. I was thinking something like "opensg-trac-notify" or
> something like that.
OK. Done:
https://lists.sourceforge.net/lists/listinfo/opensg-trac-notify . It's
not created yet but should be in a few hours.
On Tue, 2006-08-29 at 15:09 +0200, Haykel BEN JEMIA wrote:
>
> Or you can use the RSS feed of the ticket system. This way you read
> all new tickets along with the news in your breakfast ;) The link is
> in the bottom of the page "Download in other formats: RSS Feed":
> http://opensg.vrsource.org/trac/query?status=new&status=assigned&status=reopened&format=rss&order=priority
I haven't quite gotten used to RSS feeds. I still prefer email.
On Tue, 2006-08-29 at 08:10 -0500, Allen Bierbaum wrote:
>
> My counter argument to this is that the reason I use javadoc style
> documentation blocks (ie. /** ... */ and @param, @return, etc) is that
> some of the editors I use support that format and understand it. I
> don't know any that understand the alternative doxygen syntax. If
> having tools support for comment blocks is at all desirable javadoc
> style is probably the way to go. It also allows people that already
> code in java to transfer their knowledge a little easier.
What kind of support do the tools give you?
> I would modify this rule with "if it is one or two clicks away and
> obvious that you can click to find it".
Blue text not obvious enough? I could make it blink! ;)
Thanks for all your feedback!
Dirk
-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Opensg-users mailing list
Opensg-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/opensg-users
