Re: plot templates and options lists for set, plot etc.

[Robert T. Short]

John W. Eaton wrote:
> On 16-Sep-2009, Thorsten Meyer wrote:
>
> | Thorsten Meyer wrote:
> | > Here is a patch implementing struct and cell array arguments for the set 
> function.
> | > 
> | > I have impplemented the matlab behaviour (as I understand it ...). See the tests
> | >  added to the patch for the details.
> | > 
> | > Could somebody please review the patch (what I do in the sources is still a lot
> | > of trial and error):
> | >  - Have I got the types of the various variables right?
>
> | >  - Is it ok to add doxygen style comments to the new methods? (the
> | >    doxygen docs
>
> I don't use Doxygen, so I'm unlikely to remember to add the markup in
> the comments I write.  If we decide to do this, then I think we should
> try to do it on a more global scale.
>   
One of the biggest problems with becoming a contributor to octave is 
trying to understand the structure and flow of the software.  Even after 
spending hours attempting to figure octave out I still don't really 
understand how things go together.  It is easy to say "ask for help" but 
such questions usually produce only perfunctory answers.

As far as I am concerned the consistent use of a tool like Doxygen is a 
convenient way ensuring that the code is appropriately and consistently 
commented.

We have standards for documenting m-files and oct-files so that the user 
is presented with consistent help text, why would we not do such a thing 
for the source code?  As much pain as it would be the payoff would be 
significant over time.


I don't care what tool we use, but doxygen seems to have become more or 
less a standard and it will produce various sorts of UML diagrams 
including static structure diagrams.  It will do this without any 
comments but the diagrams become very difficult to follow without some 
comments.  The downside to doxygen-style markup is that the comments 
themselves get a little clumsy, but that is far more true of the texinfo 
style doc structure we impose on user functions.

Just in general, it seems we should have a minimum level of comments in 
each file.  A header that describes what the classes are for, some 
comments for each method and some comments for all data elements.

Just some thoughts.

Bob