Question about Doxygen documentation
Moderator: Forum Moderators
-
- Posts: 27
- Joined: November 20th, 2020, 5:07 am
Question about Doxygen documentation
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.
I mean something like the tutorial for using the Matrix class of Eigen: https://eigen.tuxfamily.org/dox/group__ ... Class.html
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?
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?
- Pentarctagon
- Project Manager
- Posts: 5566
- Joined: March 22nd, 2009, 10:50 pm
- Location: Earth (occasionally)
Re: Question about Doxygen documentation
Sure.
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
- Generally much effort & time would it take to review and merge this kind of pull request?
There are definitions for certain pieces of functionality, if that's what you mean.CrawlCycle wrote: ↑November 20th, 2020, 5:11 pm
- Are there standard terminologies for describing different concepts in the code base?
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.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?
Thanks.
- Is it ok to use LaTex equation / Graphviz diagram in the user documentation?
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
take one down, patch it around
-2,147,483,648 little bugs in the code
-
- Posts: 27
- Joined: November 20th, 2020, 5:07 am
Re: Question about Doxygen documentation
- 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 theconfig.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?
- The
- Pentarctagon
- Project Manager
- Posts: 5566
- Joined: March 22nd, 2009, 10:50 pm
- Location: Earth (occasionally)
Re: Question about Doxygen 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 Which entities in the code base need more documentation?
CrawlCycle wrote: ↑November 20th, 2020, 11:38 pm Theconfig.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
take one down, patch it around
-2,147,483,648 little bugs in the code
- Celtic_Minstrel
- Developer
- Posts: 2229
- Joined: August 3rd, 2012, 11:26 pm
- Location: Canada
- Contact:
Re: Question about Doxygen 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, 5:11 pm Is it ok to use LaTex equation / Graphviz diagram in the user documentation?
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.CrawlCycle wrote: ↑November 20th, 2020, 11:38 pm Theconfig.cpp
file seems to enable adding new WML tag.
Re: Question about Doxygen documentation
Well, if the generated HTML were hosted on the website, users wouldn't have to generate it themselves...Celtic_Minstrel wrote: ↑November 22nd, 2020, 7:49 amI 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, 5:11 pm Is it ok to use LaTex equation / Graphviz diagram in the user documentation?
Wesnoth-related GitHub repos:
General mods collection, SotBEEE, AToTBWaTD, The Earth's Gut, A Little Adventure, FtF
Social media: Mastodon: @egallager@treehouse.systems, Steam: egallager
General mods collection, SotBEEE, AToTBWaTD, The Earth's Gut, A Little Adventure, FtF
Social media: Mastodon: @egallager@treehouse.systems, Steam: egallager
-
- Posts: 27
- Joined: November 20th, 2020, 5:07 am
- Celtic_Minstrel
- Developer
- Posts: 2229
- Joined: August 3rd, 2012, 11:26 pm
- Location: Canada
- Contact:
Re: Question about Doxygen documentation
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.
- Pentarctagon
- Project Manager
- Posts: 5566
- Joined: March 22nd, 2009, 10:50 pm
- Location: Earth (occasionally)
Re: Question about Doxygen documentation
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
take one down, patch it around
-2,147,483,648 little bugs in the code