Document roadrunner internals

[andrewhu-uw]

As a part of preparing for #520, we need to document how roadrunner actually works, so that when someone tries to modify it as will be necessary to create dynamic model editing, they won't have to reverse engineer the entire system.

My plan right now is to write some more documents that will be put on the wiki

[hsauro]

We definitely need some internal documentation.

On Thu, Dec 20, 2018 at 11:31 AM Andrew Hu notifications@github.com wrote:

As a part of preparing for #520 https://github.com/sys-bio/roadrunner/issues/520, we need to document how roadrunner actually works, so that when someone tries to modify it as will be necessary to create dynamic model editing, they won't have to reverse engineer the entire system.

My plan right now is to write some more documents that will be put on the wiki

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/sys-bio/roadrunner/issues/521, or mute the thread https://github.com/notifications/unsubscribe-auth/ABAZDqnk7meB11MV3pGgF5jSpsS_rOMlks5u6-VfgaJpZM4ZcyHK .

-- Herbert Sauro, Associate Professor University of Washington, Bioengineering 206-685-2119, www.sys-bio.org hsauro@uw.edu Books: http://books.analogmachine.org/

[luciansmith]

I would strongly recommend using a system like Doxygen, where the functions inside roadrunner are documented in-place, and those documents can then be pulled out automatically to create an external documentation site. An overview would not be amiss, but again, putting it inside the roadrunner source code would mean that as roadrunner evolves in the future, the documentation for it is right next to the parts that they document, so you at least have a chance of noticing, when you change things, that you also need to change the docs.

It may be that this is exactly the system you're talking about, but I got worried when you said 'wiki' ;-)

[andrewhu-uw]

I like the four kinds of documentation model.

• Learning oriented
• Goal oriented
• Understanding oriented
• Information oriented

Inline documentation would mostly be information oriented, and we're definitely missing a lot of it. However, what I was going for here was more on the understanding oriented side of documentation. As of now, when you look at the internals, there is neither any explanations nor references. What I think about when I started working on the backend, was that I needed an explanation of the pipeline, and most of the LLVM stuff I could google. So, my plan was to add some explanation of the LLVM pipeline to the wiki, and then maybe document some of the LLVM heavy parts of the code with documentation comments

[hsauro]

I think Andrew is on the right track, we do need internal documentation on roadrunner. Whether it should be a wiki or doxygen I'm not sure. Also I'm not sure how much the internal API needs to be formally documented in something like doxygen (PS We use readthedocs now). One thing I've discovered about our documentation especially the user docs is that I can't easily edit them because of all the hoops necessary to make the doc visible. In one sense a wiki would be much easier to edit as it doesn't require too much specialist knowledge.

Herbert

On Thu, Dec 20, 2018 at 12:01 PM Lucian Smith notifications@github.com wrote:

I would strongly recommend using a system like Doxygen, where the functions inside roadrunner are documented in-place, and those documents can then be pulled out automatically to create an external documentation site. An overview would not be amiss, but again, putting it inside the roadrunner source code would mean that as roadrunner evolves in the future, the documentation for it is right next to the parts that they document, so you at least have a chance of noticing, when you change things, that you also need to change the docs.

It may be that this is exactly the system you're talking about, but I got worried when you said 'wiki' ;-)

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/sys-bio/roadrunner/issues/521#issuecomment-449118807, or mute the thread https://github.com/notifications/unsubscribe-auth/ABAZDltiOEgGE25ebQ7HNuLAftydlyxlks5u6-xqgaJpZM4ZcyHK .

-- Herbert Sauro, Associate Professor University of Washington, Bioengineering 206-685-2119, www.sys-bio.org hsauro@uw.edu Books: http://books.analogmachine.org/