Re: [eigen] Proposal: documentation for Eigen3

[ Thread Index | Date Index | More Archives ]

Benoit Jacob wrote:
> Yes, wikis are great to allow people to contribute more easily.
> However, I think I still prefer Doxygen, for a few reasons:
>  - it makes it much more easy, while writing documentation, to link to
> doxygen-generated docs for classes and methods.

Isn't it possible to have it both ways?   Nowadays Eigen's wiki and doxygen 
documentation coexist rather nicely.

>  - a wiki can disappear overnight if we do a mistake (rm
> eigen_wiki.db) on the server.

I believe there would be a fair number of users who would gladly store backups 
for Eigen's wiki.

>  - a wiki can't be read offline

I believe that's possible, provided some steps are taken.  For example, the 
following mediawiki extensions appears to be very promising.

>  - some of our users (e.g. willowgarage) embed a build of our dox into
> their own dox. A wiki wouldn't allow them to do that easily.
>  - it's good  to be able to distribute the dox alongside the software.

Using a wiki for the documentation doesn't take that away.

>  - dox files are actual files, and moreover have a very simple syntax,
> they're almost just plain text files. Bonus for the long-term.
>  - when one does a modification in the code, having the dox in the
> same hg repo allows to adapt them simultaneously, keeping it in sync.
> When we branch the code, we automatically branch the dox. With dox on
> the wiki, it would be hard to maintain dox for Eigen 2.0, 3.0, 3.1,
> ..., eventually 4.0.

With enough users you could simply let the wiki "ferment" over time.  I 
believe there is a considerable number of users who are more than willing to 
contribute to the project and editing a wiki is a terribly easy way to do just 
that.  Moreover, it would make it possible for the documentation to cover 
corner cases which otherwise would remain undocumented.

Rui Maciel

Mail converted by MHonArc 2.6.19+