Page MenuHome

Initial improvements to doxygen config and structure. (T73140)
Changes PlannedPublic

Authored by Jonas Printzén (ZPU) on Jan 19 2020, 7:31 PM.

Details

Summary

This will introduce updated structure and visual styles for doxygen usage in blender code.
It is a first of a few expected patches to make generated doxygen html material useful and compelling.

  1. doc/doxygen/Doxyfile was altered to provide more structured results.
  2. Layout-control and CSS Style-sheet was added to start adopting Blender visual style.
  3. A few notes on how to create improved structures with doxygen was included.
  4. Examples of how to include images

No actual code was changed, only doxygen config and comments.

Build doxygen output and give feedback on the result. This is a first step ...

Diff Detail

Event Timeline

Jonas Printzén (ZPU) retitled this revision from Initial improvements to doxygen config and structure. to Initial improvements to doxygen config and structure. (T73140).Jan 19 2020, 7:38 PM

Sorry. Don't think that I have enough expertise in Doxygen as it is used in Blender to give you useful guidance or criticism. Thank you for thinking of me, though. As noted in T73140, I think @Campbell Barton (campbellbarton) is your better bet, if he has time.

Campbell Barton (campbellbarton) requested changes to this revision.EditedJan 20 2020, 5:58 AM

First pass review.

  • Avoid noisy changes (replacing \ for @ in this case), it makes the diff harder to review, increases chance of merge conflicts and isn't related to improving structure.

    If this is done - it can be handled as a separate patch or script which automates the change.
  • I don't think it's appropriate to for doxygen docs to include text about the blender organization or photos of people. This kind of content can be put elsewhere.

    In general I'd rather doxygen focuses on the current state of the code-base, which typically excludes text about the project, people, it's history... etc.

    Although there may be some rare exceptions where necessary to make sense of the current state of the code.

    More general project level information can be added to the wiki for example & linked to from the doxygen docs.
  • This down-grades the Doxyfile to an older version, removing properties, changing warning & verbosity levels. There are enough unrelated changes it looks like the settings were copied from another project. Please only make changes needed for this patch.

After applying this patch, the docs failed to build for me, with the error:

warning: kpathsea: configuration file texmf.cnf not found in these directories: /usr/bin:/usr/bin/share/texmf-local/web2c:/usr/bin/share/texmf-dist/web2c:/usr/bin/share/texmf/web2c:/usr/bin/texmf-local/web2c:/usr/bin/texmf-dist/web2c:/usr/bin/texmf/web2c:/usr:/usr/share/texmf-local/web2c:/usr/share/texmf-dist/web2c:/usr/share/texmf/web2c:/usr/texmf-local/web2c:/usr/texmf-dist/web2c:/usr/texmf/web2c://texmf-local/web2c:/://share/texmf-local/web2c://share/texmf-dist/web2c://share/texmf/web2c://texmf-local/web2c://texmf-dist/web2c://texmf/web2c.
This is pdfTeX, Version 3.14159265-2.6-1.40.20 (TeX Live 2019/Arch Linux) (preloaded format=latex)

Even though this is something I could investigate & solve, I'd prefer the scope of this patch be reduced to make it less hassle to review.

This revision now requires changes to proceed.Jan 20 2020, 5:58 AM
source/blender/windowmanager/WM_api.h
102–106

This goes against our comment code-style, to include function comments in the code, not the headers:

See https://wiki.blender.org/wiki/Style_Guide/C_Cpp#Comments (API Docs) "Keep comments close to code."

For rationale on this see: https://softwareengineering.stackexchange.com/a/299666/99957

Jonas Printzén (ZPU) planned changes to this revision.Jan 22 2020, 3:10 PM

OK, feedback received.

I will re-visit the attempt this weekend to 'reduce noise' and remove content.

(This is in my eyes successful progress learning about the teams mindset.)