Documentation

All discussion on project related documentation including source docs, manuals, and tutorials go here.
Post Reply
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Documentation

Post by DavidD »

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).
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

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
User avatar
raevol
Posts: 3093
Joined: 07 Aug 2011, 01:12
Location: Caldera

Re: Documentation

Post by raevol »

Documentation would be AMAZING!
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Documentation

Post by Zini »

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.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

@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.
User avatar
raevol
Posts: 3093
Joined: 07 Aug 2011, 01:12
Location: Caldera

Re: Documentation

Post by raevol »

Code documentation would be amazing for new developers. Always good to reduce the barrier to entry.
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

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.
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.

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?
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

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?
If it has to do with the functions themselves, then please do that in the header and/or source files themselves.
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. :)
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Documentation

Post by Zini »

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.
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.
DavidD
Posts: 17
Joined: 25 Jun 2016, 22:33

Re: Documentation

Post by DavidD »

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.
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.

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.
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. :)
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.
Post Reply