1. gyrokinetics Avatar gyrokinetics
  2. gs2
  3. gs2
  4. Issues

Documentation

Issue #10 new
David Dickinson created an issue

We have a bit of in code documentation through the odd comment -- I think it would be helpful to greatly expand on this.

Some of our comments are currently Doxygen format -- whilst this suggests Doxygen might be the way to go, I've found it difficult to use this to produce good quality documentation (i.e. something useful for users, rather than developers). I've had a good experience with the python package FORD (this is developed by someone currently at Oxford). It's quite configurable so I think we should actually be able to set it up to recognise Doxygen format comments. Examples of the html documentation that this tool produces are available here in particular I've found FIDASIM gives a decent demo of what can be done. We'd be able host the generated documentation on the bitbucket.io site.

Comments (7)

  2. Stephen Biggs-Fox

    +1

    The FIDASIM docs look good to me.

    As noted on the Ford page: "Ford was written due to Doxygen’s poor handling of Fortran and the lack of comparable alternatives." This suggests that Doxygen is a good tool but not for Fortran projects.

    They also note: "The documentation should be easy to write and non-obtrusive within the code." This examples in the FIDASIM are indeed non-obtrusive.

    I would say we also want some guidance for developers on what is expected in terms of in-code documentation (and other documentation for that matter) via the CONTRIBUTING document.

  3. Stephen Biggs-Fox

    Did this ever get anywhere? I'm guessing not. I think we should just add a branch with a FORD configuration file and automatically generate some documentation as a starting point. Just because then we will know what comments get included / excluded so we can fix them while making other edits. Presumably, the generated documentation would then be hosted on the wiki or similar?

  4. David Dickinson reporter

    Yes it's in 8.0.1 -- make doc should build it.

    The documentation won't be on the wiki but I'm working on getting it on the project website.

  6. David Dickinson reporter

    We could, I was tempted to keep it around to remind us that we need to actually write documentation/for those looking to contribute to the project this is an ongoing task they could help with.

  8. Log in to comment
Assignee
Type
proposal
Priority
minor
Status
new
Component
–
Milestone
–
Version
–
Votes
2
Watchers
5
Jira: the preferred issue tracker for Bitbucket. Join the team!