Suggestions: Code Documentation and Readability

[n01r]

Code Documentation and Readability

I was asked to give feedback on what information I would wish to have as a user when I want to write a plugin for PIConGPU and thus I collected some ideas.

How is the simulation domain organised inside the code in general and down to the particles in detail?

• Schematic pictures (about blocks, supercells, lists of frames, particles in frames and their attributes)

What basic framework do I need to have before I can implement the methods I want to use in my plugin?

• Availability of skeletal prototypes for plugins to adapt to the 'customer's' needs

  they should be commented in detail to make the user grab the thoughts behind the code structure
  (For an orientation section 4.1 in Benjamin's thesis was quite instructive)

What particle attributes are there and how can they be accessed?

• a picturesque "tree" of all the available namespaces,a short explanation of their substructure and where to find what

Which operators have been overloaded and what basic functions are already available to the user?

• e.g. vector calculation methods

[ax3l]

Hi n01r, thank you for your feedback!

We already started the documentation in the wiki and what you are looking for should be placed in the section Developer Documentation.

How is the simulation domain organised inside the code in general and down to the particles in detail?
Schematic pictures (about blocks, supercells, lists of frames, particles in frames and their attributes)

great, let us write a new page for that, just explaining that abstract objects.

Availability of skeletal prototypes for plugins to adapt to the 'customer's' needs.

I think based on the section above, the link in the wiki so far to Benjamin's diploma thesis works for that.
But I would like to review/add-a-new section for the wiki. (Would you like to do that? It is always quite good to read a manual from someone who just understood the stuff and still has the pitfalls in mind.)

What particle attributes are there and how can they be accessed?

Partly related to that part of the libPMacc user documentation.
Also relevant for a new section/page for the general PIConGPU user documentation.

Which operators have been overloaded and what basic functions are already available to the user?

• e.g. vector calculation methods

@psychocoderHPC Probably a part of the libPMacc documentation for PMacc::math::? Right now most of the overloaded vector operators are performed dot wise. Everything else can be taken from PMacc::math:: (if implemented).

[PrometheusPi]

Great suggestions!
I would like to add, that a detailed user description for each plugin should be added in the PIConGPU User Documentation.

[ax3l]

Great idea. That is ... unfortunately ... not the case yet (only the short version in the command line manual is provided).
I also think that plugins are the part of the code that should be above-averaged documented.
@PrometheusPi Please add that point as a to-do to the PIConGPU User Documentation.

[PrometheusPi]

@ax3l I agree with you, that the plugins should be documented above-average.
I will add this to the to-do-list and will create a template in the PIConGPU User Documentation

[n01r]

I will try to put my little experience with producing a running plugin into a little manual in the wiki, then.

[PrometheusPi]

added an extra page for user plugin documentation
PIConGPU-User-Documentation - Plugins