On Mar 10, 2009, at 07:38 , Sylvain Joyeux wrote:

> I was browsing the RTT documentation, and felt ... like ... lost

Agreed ... and it's particularly bad for newbies ...

> As some other people are (I know).
>
> I was thinking about how to make it better. Two ways:
> 1. just generate a "developer" documentation and a "user"
> documentation. The
> first one is the current one, and the second one would contain
> only what we
> think is "public" API (as, for instance, TaskContext, WritePort,
> ReadPort,
> Activity, ...) leaving the underlying stuff out (scripting
> implementation,
> connection management implementation, ...).

As I've said before, Orocos has great detailed doc's but it is much
worse off at the high-level. It lacks complete system examples/
tutorials, that show how things can be connected. This makes the user
have to work through mountains of the detailed doc's trying to figure
that out for themselves. I think this is actually exacerbated by being
a framework - it isn't obvious how to put some pieces together, as the
whole point of the framework is that it is applicable to many
different applications.

> I think that split should anyway be done between the transports
> (as for
> instance CORBA) and the core.

Not sure what you mean here.

> 2. split everything into separate namespaces and have that layout
> mapped on
> disk. For instance, we would move the Conn* classes (connection
> management
> elements) into src/comm (on disk) and a RTT::Comm namespace (in
> code). That
> is a bit done for scripting (scripting-related files are in src/
> scripting
> but not in their own namespace).

It 'aint broke, don't fix it. My 2c.

Cheers
S

On Tue, Mar 10, 2009 at 12:38:27PM +0100, Sylvain Joyeux wrote:
> I was browsing the RTT documentation, and felt ... like ... lost
>
> As some other people are (I know).
>
> I was thinking about how to make it better. Two ways:
> 1. just generate a "developer" documentation and a "user" documentation. The
> first one is the current one, and the second one would contain only what we
> think is "public" API (as, for instance, TaskContext, WritePort, ReadPort,
> Activity, ...) leaving the underlying stuff out (scripting implementation,
> connection management implementation, ...).
>
> I think that split should anyway be done between the transports (as for
> instance CORBA) and the core.

I think this is a very good idea, I've have gotten lost in the
docs... :-)

> 2. split everything into separate namespaces and have that layout mapped on
> disk. For instance, we would move the Conn* classes (connection management
> elements) into src/comm (on disk) and a RTT::Comm namespace (in code). That
> is a bit done for scripting (scripting-related files are in src/scripting
> but not in their own namespace).

Yes, that would be good too.

> In general, I would prefer (2). Problem: it would take a lot of time *and*
> require that nobody touches anything while one person is doing it. I trust
> git, but I think that doing that kind of work while *in parallel* changing the
> code is calling for problems.
>
> Therefore, I would actually recommend (1), unless there is someone that can do
> a refactoring of this size in a reasonable amount of time.
>
> What do you guys think ?

1) and 2) don't seem opposed to each other so why not both, but start
with the IMO more important 1)?

I have been collecting some suggestions for OCL documentation but I
won't hijack your thread...

Best regards
Markus

On Tuesday 10 March 2009 12:38:27 Sylvain Joyeux wrote:
> I was browsing the RTT documentation, and felt ... like ... lost
>
> As some other people are (I know).
>
> I was thinking about how to make it better. Two ways:
> 1. just generate a "developer" documentation and a "user" documentation.
> The first one is the current one, and the second one would contain only
> what we think is "public" API (as, for instance, TaskContext, WritePort,
> ReadPort, Activity, ...) leaving the underlying stuff out (scripting
> implementation, connection management implementation, ...).
>
> I think that split should anyway be done between the transports (as for
> instance CORBA) and the core.
>
> 2. split everything into separate namespaces and have that layout mapped
> on disk. For instance, we would move the Conn* classes (connection
> management elements) into src/comm (on disk) and a RTT::Comm namespace (in
> code). That is a bit done for scripting (scripting-related files are in
> src/scripting but not in their own namespace).
>
> In general, I would prefer (2). Problem: it would take a lot of time *and*
> require that nobody touches anything while one person is doing it. I trust
> git, but I think that doing that kind of work while *in parallel* changing
> the code is calling for problems.
>
> Therefore, I would actually recommend (1), unless there is someone that can
> do a refactoring of this size in a reasonable amount of time.

A summer student ?

>
> What do you guys think ?

First about the restructuring code part:
I agree that all non-user API should be in nested namespaces. The public API
remains in 'RTT'. We tried to do that before (partly) by using the
'RTT::detail' namespace. This partitioning should be reflected in the
directory structure as well. All .hpp files under rtt/ are public API, all
internal headers are in rtt/something/. That would already be a big help for
newcommers.

I propose to 'submodule' code only if it is a logical unit (scripting and os
are the good examples). All other non-public code should go in src/internal (I
would rename namespace 'detail' to 'internal' in that case). You should know
that we come from an era where all code was in submodules (of submodules, like
'core/properties/marshalling') and no-one could find a header or source back in
the tree. I really don't want to go back to that. So just splitting public and
internal API could be a big win. It would then also be easier to eliminate
dead classes in the internal part.

I hope you're not in a tremendous hurry, because I would put this off in the
rtt-2.0 branch. There are lots of classes that should/will go away by
refactoring ala rtt-2.0.

About the documentation: are you refering to Doxygen, Docbook or both ?

Peter