Re: Best way to help?

[Mike Miller]

On Tue, Oct 06, 2015 at 05:56:51 -0700, LachlanA wrote:
> Thanks for processing those patches, but no, I wasn't just referring to my
> handful of patches -- there are about 40 bug reports with status "patch
> submitted" and others with patches but status "None", and so I assume that
> there is a better way to help than just submitting more patches.  Of course,
> if submitting patches is the most useful, I'd love to do that too!

More patches on open issues are always welcome! Our patch review process
may not be the most efficient, but yes, please keep patches coming.

> As a newcomer to this project, I would appreciate more documentation -- or
> for the documentation to be easier to find.  I'm making notes for myself,
> and would be happy to expand them into something like a section of Appendix
> D of the manual if there isn't already some documentation I haven't found.  

Patches welcome for documentation as well ;)

Or if you'd prefer, write a blog post or a wiki page with your notes,
and maybe it can be worked into the manual somehow.

> Is there a place that describes any of the framework of Octave (like the
> various tree walkers in libinterp/parse-tree,

Not sure about that.

> the logic behind what is in 
> liboctave  and what is in  libinterp,

I don't know that it's documented, but the convention is that numerical
code and low-level utility and OS-specific functions go in liboctave,
libinterp implements the Octave interpreter runtime. Some things have
moved from one to the other over time. Libinterp depends on liboctave,
so obviously anything that depends on libinterp also needs to be in
libinterp.

See e.g.
http://lists.gnu.org/archive/html/octave-maintainers/2013-05/msg00021.html

> the DEFUN macro,

Not that I know of.

> layering of
> octave_stream on top of C++ streams,

Not that I know of.

> error handling,

Not that I know of. This has layers in both liboctave and libinterp, and
is being cleaned up a little bit at the moment.

> the build process, what
> tools are needed to build if Makefile.am is modified etc.)?

This one is near and dear to me. The build depends on Autotools,
documented elsewhere. All build tools and dependencies should be
documented in etc/HACKING. Most things missing should be flagged as a
warning or an error at build time. Also this has been going through
major reorganization since 4.0, so if some things are documented, it's
possible they don't line up with reality now.

> If so, it would
> be great for the README to point to that documentation.

The top-level README is really intended for the end user who is
downloading Octave to build it, install it, and use it. The etc/HACKING
file is intended to be the README for hackers.

Many of your questions would be answered by inline code documentation in
doxygen format, which is an ongoing goal. There is a doxygen make rule,
just happens that not much of the libraries are documented yet.

I hope this is helpful and not too discouraging. We do intend to have
better documentation, and will welcome any help to get us there. Most of
the focus is on the user manual, and not as much effort has been put
into docs for developers.

-- 
mike