[vtk-developers] Documentation Rules

Andrew Maclean andrew.amaclean at gmail.com
Tue Dec 8 00:27:48 EST 2009


Hi David,
Please also look at: http://www.cmake.org/Wiki/VTK_Coding_Standards.
Maybe instead of creating a new page this could be expanded,
incorporating the documentation rules. Personally I prefer the term
"standards" and not "rules".

With respect to Philippe's comments below. I agree that we need some
way of handling outside documentation. Referencing here could be to
web links and also to bibliographic entries, I think both are
acceptable. However,  I think the LaTex source files (and a PDF)
should go into the VTK Journal.

Regards
   Andrew

On Tue, Dec 8, 2009 at 1:15 PM, Pebay, Philippe P <pppebay at sandia.gov> wrote:
> 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
>
>
>
> _______________________________________________
> 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
>
>



-- 
___________________________________________
Andrew J. P. Maclean
Centre for Autonomous Systems
The Rose Street Building J04
The University of Sydney  2006  NSW
AUSTRALIA
Ph: +61 2 9351 3283
Fax: +61 2 9351 7474
URL: http://www.acfr.usyd.edu.au/
___________________________________________



More information about the vtk-developers mailing list