[vtk-developers] Documentation Rules

[Pebay, Philippe P]

David

Thank you for initiating this effort. A related question is that of outside of source documentation: I have been wondering for a while as to what is the best way to reference outside documentation inside the code. Should this take the form of web links (which tend to become obsolete) to wiki pages? Or actual bibliographic entries, when available? I have used the latter approach, but it is not perfect by a long shot: for example, some references might be available to journal subscribers. Or, the document can be large and referring to it as a whole might not be particularly helpful, where a more pointed way of referencing would be more readily usable.
Another option would be the incorporation of LaTeX source files, which would be compiled in addition to the Doxygen pages.

Thoughts?

Thank you
Philippe
--
Philippe Pébay
Sandia National Laboratories

________________________________________
From: vtk-developers-bounces at vtk.org [vtk-developers-bounces at vtk.org] On Behalf Of David Doria [daviddoria+vtk at gmail.com]
Sent: Monday, December 07, 2009 6:08 PM
To: VTK Developers
Subject: [vtk-developers] Documentation Rules

Folks,

I have started compiling a list of what the documentation should look like:
http://www.vtk.org/Wiki/Documentation_Rules

Clearly I have no covered all of the cases - more will come as I
discover more typical cases. Suggestions for things to add are
welcome.

Agreement on these rules will not only help direct my efforts, but
also ensure that future code will adhere to these guidelines.

Once we establish the rules, is there a way to have KWStyle type
checks for "documentation correctness"? Something to the effect of
rejecting the commit or turning the dashboard red if the
documentation/comments do not meet the new standards? I think
requiring this is the only way to maintain good documentations -
developers seem to get in a hurry and the first thing that disappears
is the documentation - requiring it would alleviate this problem.

Thoughts?

Thanks,

David
_______________________________________________
Powered by www.kitware.com

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
http://www.vtk.org/mailman/listinfo/vtk-developers