Since I'm pretty much going through the code file by file at this point to figure out how everything works, I thought I might as well write some documentation if there is any interest.
Have you established any guidelines when it comes to writing documentation? Should it be placed on the wiki or in the code? For instance: if I want to describe how/why FileParser uses ScriptParser, should I write that as a comment in fileparser.hpp? Should I write it so that doxygen will pick it up or just write it as a normal comment? Should I just put it in the wiki?
The things I thought about writing down are examples of when/how something is used, how some classes relate to each other, as well as descriptions for classes and members if needed (e.g. State in FileParser).
Documentation
- psi29a
- Posts: 5361
- Joined: 29 Sep 2011, 10:13
- Location: Belgium
- Gitlab profile: https://gitlab.com/psi29a/
- Contact:
Re: Documentation
We use Sphinx for at least the OpenMW-CS, it would be nice to see it in OpenMW itself too.
https://github.com/OpenMW/openmw/tree/master/docs
With Sphinx (RST) you can make pdf/latex/whatever outputs.
http://www.sphinx-doc.org/en/stable/rest.html
We can use doxygen to sphinx plugin to get c++ auto-doc function for the API/functions as well.
https://github.com/michaeljones/breathe
https://github.com/OpenMW/openmw/tree/master/docs
With Sphinx (RST) you can make pdf/latex/whatever outputs.
http://www.sphinx-doc.org/en/stable/rest.html
We can use doxygen to sphinx plugin to get c++ auto-doc function for the API/functions as well.
https://github.com/michaeljones/breathe
Re: Documentation
Documentation would be AMAZING!
Re: Documentation
I think we are talking about different things here. For OpenMW-CS we have (some) end user documentation via Sphinx. There needs to be more work done on that. A lot.
But I think DavidD meant code documentation, right?
I don't think the code requires a substantial amount of documentation work, though there are probably a few spots that could be documented better. Keep in mind that too much documentation can also be a problem, because it requires additional work to keep it up to date and an outdated/incorrect API documentation is worse than none at all.
We also have the high level documentation in the wiki, that is (as mentioned before) somewhat outdated. Getting it current again would be very helpful.
But I think DavidD meant code documentation, right?
I don't think the code requires a substantial amount of documentation work, though there are probably a few spots that could be documented better. Keep in mind that too much documentation can also be a problem, because it requires additional work to keep it up to date and an outdated/incorrect API documentation is worse than none at all.
We also have the high level documentation in the wiki, that is (as mentioned before) somewhat outdated. Getting it current again would be very helpful.
- psi29a
- Posts: 5361
- Joined: 29 Sep 2011, 10:13
- Location: Belgium
- Gitlab profile: https://gitlab.com/psi29a/
- Contact:
Re: Documentation
@Zini: Code documentation (coverage) is always welcome.
Having sphinx then parse (auto-doc) this is certainly handy too.
Sphinx isn't just for writing your own hand-books or end-user documentation, it can also handle API documentation.
I have a skeleton c++ library/tool that uses sphinx for both end-user documentation and auto-doc (via doxygen) to create API documentation.
https://github.com/psi29a/datadiver
This would help also with maintaining man pages for our executables.
Having sphinx then parse (auto-doc) this is certainly handy too.
Sphinx isn't just for writing your own hand-books or end-user documentation, it can also handle API documentation.
I have a skeleton c++ library/tool that uses sphinx for both end-user documentation and auto-doc (via doxygen) to create API documentation.
https://github.com/psi29a/datadiver
This would help also with maintaining man pages for our executables.
Re: Documentation
Code documentation would be amazing for new developers. Always good to reduce the barrier to entry.
Re: Documentation
I was thinking about both, though more so architecture than code, since the structure of the code should remain mostly the same at this point, right? It would serve as an introduction to the codebase and how the different parts relate to each other. Obviously it's impossible to completely document the code at this point, and as you say, it would probably end up making maintenance a mess and leave it worse than before.Zini wrote:But I think DavidD meant code documentation, right?
I don't think the code requires a substantial amount of documentation work, though there are probably a few spots that could be documented better. Keep in mind that too much documentation can also be a problem, because it requires additional work to keep it up to date and an outdated/incorrect API documentation is worse than none at all.
As for the code, I would say that a couple of rows of description per class would be fine to write even at this stage. But should that maybe be placed on the wiki, rather than writing it inside the header file? Or should a brief explanation be placed in the code with a link to the wiki page or something?
- psi29a
- Posts: 5361
- Joined: 29 Sep 2011, 10:13
- Location: Belgium
- Gitlab profile: https://gitlab.com/psi29a/
- Contact:
Re: Documentation
If it has to do with the functions themselves, then please do that in the header and/or source files themselves.DavidD wrote:As for the code, I would say that a couple of rows of description per class would be fine to write even at this stage. But should that maybe be placed on the wiki, rather than writing it inside the header file? Or should a brief explanation be placed in the code with a link to the wiki page or something?
https://www.stack.nl/~dimitri/doxygen/m ... locks.html
It would be hell to have to track everything down all over the place.
As for the rest, I suggest writting it out in ReST so that we can use sphinx to produce pdf/latex/html/whatever and even get it hosted on readthedocs.org
Update: If you wish, I can help get the ball rolling and set things up. All that would be needed is for someone to start typing documentation.
![Smile :)](./images/smilies/icon_e_smile.gif)
Re: Documentation
Like this? Agreed. As mentioned before, it needs updating. And some additions. I was under the impression that we would have a list of the individual subsubsystem for OpenMW (mw*) with at least a minimal description what they do and how they interact. Likewise for components. But apparently not.I was thinking about both, though more so architecture than code, since the structure of the code should remain mostly the same at this point, right? It would serve as an introduction to the codebase and how the different parts relate to each other.
This would be a useful additional. More important than documentation in the code IMO. But some additional documentation on class level wouldn't hurt either. I am okay with that.
Re: Documentation
Yes, exactly like that. That was one of the first pages I looked at in the wiki, and I assume pretty much everyone who is new will do the same.Zini wrote: Like this? Agreed. As mentioned before, it needs updating. And some additions. I was under the impression that we would have a list of the individual subsubsystem for OpenMW (mw*) with at least a minimal description what they do and how they interact. Likewise for components. But apparently not.
This would be a useful additional. More important than documentation in the code IMO. But some additional documentation on class level wouldn't hurt either. I am okay with that.
Is it necessary to have both the wiki and some document generated by Sphinx? How should the two be separated enough to warrant both? Wiki as a quick reference/overview and the other document for a more definitive guide? I could see the wiki going into details anyway.
That would be great! I was thinking I'd sit down and write it as i explore the code, but I don't have a whole lot of time until the weekend. I'm mostly unsure how you want to structure the documentation right now. I have edited a wiki before, and Sphinx doesn't look too trick either so those shouldn't be a problem.psi29a wrote:Update: If you wish, I can help get the ball rolling and set things up. All that would be needed is for someone to start typing documentation.