Editing Project - Documentation
Jump to navigation
Jump to search
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 66: | Line 66: | ||
'''Description''' | '''Description''' | ||
[https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen], and [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] for | [https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen], and [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] for it's internal documentation. Ever since, there has been moderate effort to add Doxygen comments to the entire code base or to create verbose descriptions for key techniques about how Octave works (here an example for [https://octave.org/doxygen/5.2/df/d4d/Macros.html important Octave macros]). Potential reasons for this circumstance are: | ||
# Lack of developer knowledge (code grew over 25 years), many "cryptic" macros, very complex class inheritance trees: | # Lack of developer knowledge (code grew over 25 years), many "cryptic" macros, very complex class inheritance trees: | ||
#* [https://octave.org/doxygen/5.2/d0/d26/classArray.html <code>liboctave/Array</code>] | #* [https://octave.org/doxygen/5.2/d0/d26/classArray.html <code>liboctave/Array</code>] | ||
#* [https://octave.org/doxygen/5.2/d6/d68/classoctave__base__value.html <code>libinterp/octave_base_value</code>] | #* [https://octave.org/doxygen/5.2/d6/d68/classoctave__base__value.html <code>libinterp/octave_base_value</code>] | ||
# long Doxygen build time to see results of documentation effort | # long Doxygen build time to see results of documentation effort | ||
# huge size (about 2 GB), very impractical to "carry around", | # huge size (about 2 GB), very impractical to "carry around", https://octave.org/doxygen slowly responding | ||
Nevertheless, there is a need for internal documentation: | Nevertheless, there is a need for internal documentation: | ||
Line 82: | Line 82: | ||
* The internal documentation should cover the following topics (a more verbose extension of [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] [https://octave.org/doxygen/5.2/d1/d10/Hacking.html (html)]): | * The internal documentation should cover the following topics (a more verbose extension of [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] [https://octave.org/doxygen/5.2/d1/d10/Hacking.html (html)]): | ||
** Overview about the code base (liboctave, libinterp, libgui, ...). | ** Overview about the code base (liboctave, libinterp, libgui, ...). | ||
** How Octave is | ** How Octave is build (necessary tools [versions], involved scripts, ...). | ||
** The release procedure, e.g. [[6.1 Release Checklist]]. | ** The release procedure, e.g. [[6.1 Release Checklist]]. | ||
* Make the internal documentation '''obvious, easy to study and to extend, avoid effort duplication'''. | * Make the internal documentation '''obvious, easy to study and to extend, avoid effort duplication'''. | ||
Line 92: | Line 92: | ||
** Fast build time. | ** Fast build time. | ||
** Lightweight (existing) documentation system. No heavy preprocessing / code generation by custom scripts. | ** Lightweight (existing) documentation system. No heavy preprocessing / code generation by custom scripts. | ||
** As close to the source as necessary. Make it difficult to update the code while not updating | ** As close to the source as necessary. Make it difficult to update the code while not updating it's documentation. E.g. no wiki documentation for Octave's C++ files. | ||
'''Resources''' | '''Resources''' |