1,847
edits
Project - Documentation: Difference between revisions
Jump to navigation
Jump to search
Add Category:Project Ideas.
(Add Category:Project Ideas.) |
|||
| (4 intermediate revisions by 2 users not shown) | |||
| Line 4: | Line 4: | ||
[[File:SeasonofDocs Logo SecondaryGrey 300ppi.png|right|200px|link=https://g.co/seasonofdocs]] | [[File:SeasonofDocs Logo SecondaryGrey 300ppi.png|right|200px|link=https://g.co/seasonofdocs]] | ||
* GNU Octave | * GNU Octave might apply for [https://g.co/seasonofdocs Google Season of Docs (GSoD)] 2021. Discuss about your ideas and application with us by | ||
** [https://lists.gnu.org/mailman/listinfo/octave-maintainers <code>maintainers@octave.org</code>] the maintainers mailing-list (please [https://en.wikipedia.org/wiki/Posting_style#Bottom-posting bottom post]!) | ** [https://lists.gnu.org/mailman/listinfo/octave-maintainers <code>maintainers@octave.org</code>] the maintainers mailing-list (please [https://en.wikipedia.org/wiki/Posting_style#Bottom-posting bottom post]!) | ||
** [http://webchat.freenode.net?channels=octave <code>#octave</code> IRC channel] in Freenode | ** [http://webchat.freenode.net?channels=octave <code>#octave</code> IRC channel] in Freenode | ||
| Line 61: | Line 61: | ||
'''Description''' | '''Description''' | ||
[https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen] 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 its internal documentation. There has been only 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 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", https://octave.org/doxygen slowly responding | # 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 77: | Line 77: | ||
* 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 built (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 87: | Line 87: | ||
** 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 its documentation. E.g. no wiki documentation for Octave's C++ files. | ||
'''Resources''' | '''Resources''' | ||
| Line 99: | Line 99: | ||
* '''Potential mentors''' | * '''Potential mentors''' | ||
: [[User:siko1056 | Kai]] | : [[User:siko1056 | Kai]] | ||
[[Category:Project Ideas]] | |||