Question about Doxygen documentation

Discussion of all aspects of the game engine, including development of new and existing features.

Moderator: Forum Moderators

Post Reply
CrawlCycle
Posts: 27
Joined: November 20th, 2020, 5:07 am

Question about Doxygen documentation

Post by CrawlCycle »

Hi. I have some questions about the documentation for the C++ code of Wesnoth.
I think I only find 1-2 pull requests that only add Doxygen API documentation to the code.
  • Do you guys accept this kind of pull request?
  • Generally much effort & time would it take to review and merge this kind of pull request?
  • Are there standard terminologies for describing different concepts in the code base?
Beside the API documentation, I think user documentation for using the code as a library is also useful.
I mean something like the tutorial for using the Matrix class of Eigen: https://eigen.tuxfamily.org/dox/group__ ... Class.html
  • Do you guys want user documentation?
  • Is it ok to use LaTex equation / Graphviz diagram in the user documentation?
Thanks.
User avatar
Pentarctagon
Project Manager
Posts: 5526
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Question about Doxygen documentation

Post by Pentarctagon »

CrawlCycle wrote: November 20th, 2020, 5:11 pm
  • Do you guys accept this kind of pull request?
Sure.
CrawlCycle wrote: November 20th, 2020, 5:11 pm
  • Generally much effort & time would it take to review and merge this kind of pull request?
It depends - might take quite a while to review something that covers an area deep in the engine that nobody has needed to touch for a few years vs something simpler and more recently modified.
CrawlCycle wrote: November 20th, 2020, 5:11 pm
  • Are there standard terminologies for describing different concepts in the code base?
There are definitions for certain pieces of functionality, if that's what you mean.
CrawlCycle wrote: November 20th, 2020, 5:11 pm Beside the API documentation, I think user documentation for using the code as a library is also useful.
I mean something like the tutorial for using the Matrix class of Eigen: https://eigen.tuxfamily.org/dox/group__ ... Class.html
  • Do you guys want user documentation?
  • Is it ok to use LaTex equation / Graphviz diagram in the user documentation?
Thanks.
I'm not actually sure what you mean by this. Wesnoth has never been used as a library for something else as far as I know.
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
CrawlCycle
Posts: 27
Joined: November 20th, 2020, 5:07 am

Re: Question about Doxygen documentation

Post by CrawlCycle »

  • Which entities in the code base need more documentation?
    • For now, I try to find the popular entities by building Doxygen documentation with all kinds of graph.
  • I notice that config::add_child in the config.cpp file has a lot of usages (Doxygen: > 200 usages. CLion: 152 usages).
    • The config.cpp file seems to enable adding new WML tag.
    • However, the file lacks example for doing that at a quick glance.
    • Are there existing documentation for adding new WML tag?
User avatar
Pentarctagon
Project Manager
Posts: 5526
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Question about Doxygen documentation

Post by Pentarctagon »

CrawlCycle wrote: November 20th, 2020, 11:38 pm Which entities in the code base need more documentation?
At this point, you can really take your pick - the Doxygen documentation right now ranges between "old and possibly outdated" to "doesn't exist".
CrawlCycle wrote: November 20th, 2020, 11:38 pm The config.cpp file seems to enable adding new WML tag.
However, the file lacks example for doing that at a quick glance.
Are there existing documentation for adding new WML tag?
config.*pp and config_attribute_value.*pp are related to the engine's internal representation of the WML it reads, which includes modifying that representation to add or remove data. For defining brand new tags, you'd want to look in game_lua_kernel.*pp as well as the related lua files in data/lua/.
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
User avatar
Celtic_Minstrel
Developer
Posts: 2166
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Question about Doxygen documentation

Post by Celtic_Minstrel »

CrawlCycle wrote: November 20th, 2020, 5:11 pm Is it ok to use LaTex equation / Graphviz diagram in the user documentation?
I think I would recommend against it unless it seems absolutely necessary. The thing is, I suspect most people will read the documentation in the source code rather than generating an HTML version with Doxygen, so if they come across some random LaTeX in the middle, it might not be clear what it means.
CrawlCycle wrote: November 20th, 2020, 11:38 pm The config.cpp file seems to enable adding new WML tag.
This class is just a generic description of a WML file. It doesn't define what tags are allowed or anything like that - it's more of a JSON-like format in that it can hold whatever arbitrary data someone wants to put into it.
Author of The Black Cross of Aleron campaign and Default++ era.
Former maintainer of Steelhive.
User avatar
egallager
Posts: 576
Joined: November 19th, 2020, 7:27 pm
Location: Concord, New Hampshire
Contact:

Re: Question about Doxygen documentation

Post by egallager »

Celtic_Minstrel wrote: November 22nd, 2020, 7:49 am
CrawlCycle wrote: November 20th, 2020, 5:11 pm Is it ok to use LaTex equation / Graphviz diagram in the user documentation?
I think I would recommend against it unless it seems absolutely necessary. The thing is, I suspect most people will read the documentation in the source code rather than generating an HTML version with Doxygen, so if they come across some random LaTeX in the middle, it might not be clear what it means.
Well, if the generated HTML were hosted on the website, users wouldn't have to generate it themselves...
CrawlCycle
Posts: 27
Joined: November 20th, 2020, 5:07 am

Re: Question about Doxygen documentation

Post by CrawlCycle »

egallager wrote: November 25th, 2020, 5:28 am Well, if the generated HTML were hosted on the website, users wouldn't have to generate it themselves...
I think he meant most programmers.
User avatar
Celtic_Minstrel
Developer
Posts: 2166
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Question about Doxygen documentation

Post by Celtic_Minstrel »

egallager wrote: November 25th, 2020, 5:28 am Well, if the generated HTML were hosted on the website, users wouldn't have to generate it themselves...
Most people for whom the documentation is useful are developers. Unless that HTML was updated on every push (and maybe even if it's not), it's easier to just read it in the header file, because the website version could be out-of-date.
Author of The Black Cross of Aleron campaign and Default++ era.
Former maintainer of Steelhive.
User avatar
Pentarctagon
Project Manager
Posts: 5526
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Question about Doxygen documentation

Post by Pentarctagon »

There's https://devdocs.wesnoth.org/ already, which is already up to 1.15.7+dev, so I'd guess it's built off of one of the jenkins jobs.
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
Post Reply