Documentation Improvement: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Documentation Improvement!=
==Documentation Improvement!==
Without the voice of the users, the developers will not be encouraged to make any changes to the existing system. On the [[{{TALKPAGENAME}}|discussion page]], please "sign" the wiki if you agree (or disagree!) with any of the following proposals or have any comments or stories about your experiences.
Without the voice of the users, the developers will not be encouraged to make any changes to the existing system. On the [[{{TALKPAGENAME}}|discussion page]], please "sign" the wiki if you agree (or disagree!) with any of the following proposals or have any comments or stories about your experiences.


Line 65: Line 65:
It seems like it would be extremely informative (instead of going digging through cxx files for this type of information, and often still not finding it).
It seems like it would be extremely informative (instead of going digging through cxx files for this type of information, and often still not finding it).


==Virtual Member functions (defined in superclasses)==
I will often call a function on a derived class, go to look for it, and find that it is not there! Of course the answer is that it lives in a superclass, but there could be users with limited c++ experience that would not know to look there. Could there be some kind of pointer to the superclass function on the


For example, in my code I often do this:
==Action==
I think it would take someone with some knowledge of the class less than 10 minutes to go through and make these type of statements, and it would IMMENSELY improve usability for new (and all) users.
 
The biggest problem is that the documentation is generated from the source (which is an amazing feature), but it prevents non-write-access members of the community from helping with this process. Is there anything we can do about this? (UPDATE: The ITK project is working on editing the documentation directly through the http Doxygen interface. Hopefully VTK will follow suit.)
 
 
==FAQ==
===I know a particular function exists, but it doesn't appear in the class Doxygen===
A user will often call a function on a derived class, go to look for it, and find that it is not there! The answer is that the function is defined in a superclass.
 
As an example, a user does this:
<source lang="cpp">
<source lang="cpp">
vtkPolyData* polydata = vtkPolyData::New();
vtkPolyData* polydata = vtkPolyData::New();
Line 76: Line 84:
</source>
</source>


However, if I go here:
Then goes to look for the function documentation:
http://www.vtk.org/doc/nightly/html/classvtkPolyData.html
http://www.vtk.org/doc/nightly/html/classvtkPolyData.html
and search for "setpoints", there is nothing!
and searches for "SetPoints" and finds no matches!


Of course going up the hierarchy to:
Going up the hierarchy to:
http://www.vtk.org/doc/nightly/html/classvtkPointSet.html
http://www.vtk.org/doc/nightly/html/classvtkPointSet.html
will find the answer, but often one has to go up 3 or 4 levels and by that time it can get very confusing.
will find the function, but often one has to go up 3 or 4 levels and by that time it can get very confusing.
 
On the vtkPolyData page, could there be something like:
<source lang="cpp">
virtual void SetPoints (vtkPoints *) (see vtkPointSet)
</source>
 
==Action==
I think it would take someone with some knowledge of the class less than 10 minutes to go through and make these type of statements, and it would IMMENSELY improve usability for new (and all) users.


Thoughts/comments? If I am the only one that finds this a bit annoying, then fine. But if others agree with me, maybe I can start some sort of wiki "sign up" page with a list of the classes and who will improve the documentation pages? With a group effort I don't think it would take long at all to clean up.
Clicking the "List of all members." link provides exactly this "all possible functions" list!

Latest revision as of 21:00, 28 November 2010

Documentation Improvement!

Without the voice of the users, the developers will not be encouraged to make any changes to the existing system. On the discussion page, please "sign" the wiki if you agree (or disagree!) with any of the following proposals or have any comments or stories about your experiences.

Function Parameters

A user may say "In the function I am writing today, I need to perform a ray/triangle intersection". Being a good student of computer graphics, he looks for the octree class, and finds vtkOBBTree. He searches for "intersection" and finds: <source lang="cpp"> virtual int IntersectWithLine (double p1[3], double p2[3], double tol, double &t, double x[3], double pcoords[3], int &subId) </source>

The description is: "Return intersection point (if any) of finite line with cells contained in cell locator."

Many users first thoughts are: "What is a cell locator? What is 'tol'? What is 't'? What is 'subId'? What is 'x'? What is 'pcoords'? What are 'p1' and 'p2'? Why does it return an int?"

I recommending having first, if at all possible, a sentence in the description to describe the function in "non-VTK" terms. Something like "Return the intersection point (if any) of a finite line with a 3D mesh."

A table like this would also be extremely helpful: (if you see a '?' in the table, that means I'm not sure about this particular cell of the table :) )

Variable Description Reasonable value
Return value 1 if the line intersected the polydata, 0 otherwise n/a
p1 & p2 The end points of the line segment to be intersected with the polydata n/a
tol Accounts for floating point precision problems when performing ray/cell intersections 0.01
t determines ? ?
x Return the coordinate of the intersection n/a
subId Return the index of the cell relative to a triangle strip, if applicable (rarely used) n/a
pcoords ? ?

Default values

This applies to many, many, classes, but let's take an example.

Can things like this (from the constructor of vtkOBBTree) be listed on the class reference websites? <source lang="cpp">

 this->Level = 4;
 this->MaxLevel = 12;
 this->Automatic = 1;
 this->Tolerance = 0.01;

</source>

A little section like: (again, '?' indicates I'm not sure of the value in this example)

Variable Description Default value
Level I don't even know what this is and I use this class 4
MaxLevel The depth of the tree? 12
Tolerance Determines ? 0.01


It seems like it would be extremely informative (instead of going digging through cxx files for this type of information, and often still not finding it).


Action

I think it would take someone with some knowledge of the class less than 10 minutes to go through and make these type of statements, and it would IMMENSELY improve usability for new (and all) users.

The biggest problem is that the documentation is generated from the source (which is an amazing feature), but it prevents non-write-access members of the community from helping with this process. Is there anything we can do about this? (UPDATE: The ITK project is working on editing the documentation directly through the http Doxygen interface. Hopefully VTK will follow suit.)


FAQ

I know a particular function exists, but it doesn't appear in the class Doxygen

A user will often call a function on a derived class, go to look for it, and find that it is not there! The answer is that the function is defined in a superclass.

As an example, a user does this: <source lang="cpp"> vtkPolyData* polydata = vtkPolyData::New(); vtkPoints* points3D = vtkPoints::New(); // ... fill points3D .... polydata->SetPoints(points3d); </source>

Then goes to look for the function documentation: http://www.vtk.org/doc/nightly/html/classvtkPolyData.html and searches for "SetPoints" and finds no matches!

Going up the hierarchy to: http://www.vtk.org/doc/nightly/html/classvtkPointSet.html will find the function, but often one has to go up 3 or 4 levels and by that time it can get very confusing.

Clicking the "List of all members." link provides exactly this "all possible functions" list!