The missing programmers guide.
For now this is the front page of the community-created OpenFOAM programmer's guide. The contents of the guide itself are located under the subcategories heading below
1 Submission guidelines
This isn't a how-to guide. It's a what's what guide. Articles here should be like encyclopedia articles describing the chosen subject.
This is a supplement to the auto-generated Doxygen documentation. You do not need to go into the minute details; you do not have to list every available method of a class. Describe its purpose as a human would to another human.
1.1 Types of articles
- Overview - these articles give a broad overview of complex subjects, and cover a wide range of OpenFOAM classes. For example, see Finite volume method (OpenFOAM) and OpenFOAM guide/objectRegistry.
- Classes - these articles are specific to a single class. They describe the purpose of the class, but do not need to go into the fine details of its implementation. For example, see tmp, or PrimitivePatchInterpolation;
- Code snippets - these articles are specific to a small section of code, usually a complex or confusing one. They describe its purpose / implementation. For example, see: lduMatrix;;faceH, or PointVolInterpolation.
- Others - Some articles don't fit well into the encyclopedia format, for instance: Use bananas (a tip suggested by Hrvoje Jasak during a training workshop). Just use common sense!
1.2 Naming conventions
1.2.1 DO NOT USE DOUBLE SEMI-COLONS ::
It may be tempting to create an article named lduMatrix::negSumDiag. Unfortunately this wiki has Semantic MediaWiki installed, which will interpret these links as properties, and mess everything up. If you must use the scope operator in a link, use semicolons instead: lduMatrix;;negSumDiag.
1.2.2 Prepend all article names with OpenFOAM guide/
To keep the programmer's guide in its own space and prevent any naming collisions, prepend your article name with OpenFOAM guide/:
- my awesome article INCORRECT
- OpenFOAM guide/my awesome article CORRECT
1.2.3 Organize articles by category, not title
It's still early so we can change this...
We need a way to organize the articles, like how a book is organized with chapters and sub-chapters. There are two options:
- Use the article title - subpages can be used to sort articles into a hierarchical tree according to their titles
- behaviour - this behaves more like a book
- advantage - each subpage lists its parent at the top - in other words, you can see what chapter / sub section you are in
- disadvantage - parents do not list their child pages - in other words there are no table of contents. Creating one for every page would be an exercise in high-maintenance
- Use the category system - articles can be placed in categories, and these categories get sorted into a hierarchy
- behaviour - this behaves more like an encycolpedia (it's how Wikipedia works right now)
- disadvantage - article pages and category pages are separate - to see the hierarchy you have to visit a different page.
- advantage - category contents are automatically updated - in other words, the table of contents is self-generating
We have decided to stick with the category method. Feel free to discuss this on the discussion page.
For now, use the existing categories. We will expand them as necessary.
Another thing that is open for discussion.
I believe it is best if we don't sign our articles. Signing an articles discourages others from making edits. MediaWiki has built-in author tracking under the history tab of each article.
This category has the following 5 subcategories, out of 5 total.