Dirk Reiners wrote:
> 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! ;).
>
>
Sounds a little like a chicken and the egg problem. You want the source
files clean so when a developer goes there that already knows what they
want they can get to it quickly. But at the same time you want good
documentation that is up-to-date so users don't need to look at the
source.
I think the key choice to make here, is what is more important. Having
good up-to-date documentation for users or having clean source files for
developers. (personally I find well documented source files to be more
useful as a developer as well, but maybe I am odd. :)
>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.
>
>
Agreed on the methods. Put the documentation wherever the
implementation is. Note, that for templates this means they would be in
the header files with the methods. It also means that .inl
implementations would have documentation in the "header" file as well.
>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.
>
>
So... what is the outcome here? Are you willing to consider putting the
member variable documentation with the member variables in the header file?
[snip]
>>>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 think we need to clarify something here. I see the programs in the
source tree breaking down similar to this:
- tutorials: Simple programming examples that have very little code and
are helpful for learning
ex: 10loading.cpp
- tests: Unit tests or very obtuse pieces of code to excersize specific
functionality
ex: geomtry_unit_test
- examples: Potentially involved examples of how to use various aspects
of OpenSG.
ex: ShadowMapping, billion polygon renderer, osgSceneViewer
In my book, example doesn't have to mean simple or small. It is meant
to be an example of how to do something, not a tutorial about how to
learn something. That said, I am sure there will be some examples that
are very simple and just demonstrate some small functionality but one
thing OpenSG is really missing that examples can help with is full
examples of complex capabilities. An example of how to use
cluster-based rendering is something we need an example of, but it is
definitely not going to fit into something smaller then the SSM. It may
not even use the SSM because it needs a more complex scene manager.
I am all for using something very simple for tutorials, but we need full
examples. I want people to see the power of OpenSG to do advanced things.
>>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.
>
>
I will try to get it setup in the next couple of days.
>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?
>
>
With visual slickedit it gives autocomplete of the tokens and the
ability to pull up a GUI for editing just the documentation fields.
There are other tools though that have other types of support (example:
documentation extraction, GUI helpers, templates, etc). It just comes
down to the fact that the javadoc format is more widely used (because of
java) and this means there is more chance to have tools besides doxygen
that support editing or use of the documentation.
This isn't a huge argument against using the doxygen native format, but
it may be something to consider.
>>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! ;)
>
>
>
I was thinking more of if the user says to themselves "I don't
understand, what does this mean", do they realize they should just click
on the blue text in front of them. In most cases I would think this is
probably true.
-Allen
>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
>
>
>
-------------------------------------------------------------------------
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
