Some guidelines on how to write proper documentation for PureBasic.

1. Commands Descriptions

About writing proper descriptions in the commands.

  1. Include references to other commands (same library and other libraries, and to the reference chapters as well) whenever this makes sense.

    Links to other sections of the manual can be easily created via the following tags:

    @@FunctionName

     — direct link to the function (any library).

    @Link "DrawImage" "DrawImage()"

     — direct link to a command (same library).

    @Link "Image/DrawImage" "DrawImage()"

     — direct link to a command (other library).

    @LibraryLink "Image" "text"

     — link to the main page of a library.

    @ReferenceLink "colortable" "text"

     — link to a chapter in reference guide.

    Use the @@FunctionName notation wherever a link in the form @Link "Library/Function" "Function()" is not necessary, because the former is shorter. Use the general @Link form only to create links with a different text than the function name.

    The following link form is still supported for compatibility, but should no longer be used:

    @FastLink "DrawImage()"

     — direct link to a command (same library) short version.

  2. For the function syntax line, only include a Result =  if the function actually returns something.

    The Result part should indicate the type of the return value:

    @Function Result$ = ReplaceString(...
    @Function Result.f = ValF(...
    @Function CloseWindow(...
  3. Always include a parameters and return value section. If they are empty, use the shortcuts @NoParameters or @NoReturnValue but do not leave them out!

  4. Describe ALL parameters to a function with a @Parameter statement, even if their meaning seems obvious. Multiple parameters can be described in one go if they belong together, but every parameter must be listed somewhere:

    @Parameter "x, y, Width, Height"
      Specifies the location and dimensions of the box to draw.
  5. Mark optional parameters with an @OptionalParameter line, and in the text describe what happens if they are omitted:

    @OptionalParameter "Depth"
      Specifies the depth for the new image. [...] The default depth is 24-bit.
  6. Keep the @Description section short. If there is extra stuff to say, put it in a @Remarks section after parameters and return value.

  7. Stuff to put in the @SeeAlso section:

    • Commands that are mentioned/linked elsewhere in the current command page (e.g. in the @Remarks section). This grants quick access to user who have read the whole page.

    • Commands that must be used to create a parameter for the current command:

      ImageGadget()ImageID()

    • All open/close commands that correspond to the current command:

      OpenConsole()CloseConsole()
      FreeImage()CreateImage(), LoadImage(), CatchImage()

    • Commands that have to be used together with the current command:

      NextDirectoryEntry()ExamineDirectory(), FinishDirectory(), DirectoryEntry[Name, Type, etc]()

    • Commands that perform a similar/related function as the current command:

      Line()LineXY()
      Print()PrintN()

    • Other commands that users might want to know about in relation to the current command. Don’t overdo it though: don’t list all commands of the current library, etc.

  8. Order of sections for a function:

    • @Function

    • @Description

    • @Parameter (for each parameter)

    • @ReturnValue

    • @Remarks (optional)

    • @Example (optional, can be more than one)

    • image(s) (optional)

    • @SeeAlso

    • @SupportedOS

    Images should be accompanied by the code that produced the image/screenshot, as an example so that users can recreate the same image and experiment with the code.

2. Taking Screenshots

Screenshots should be taken with the same tool and using consistent settings. Unless dealing with OS specific things, they should be taken under Windows 7.

  1. Use Greenshot

    To take screenshots of whole windows:

    • In the preferences of Greenshot, under Capture  Window capture, select “Window capture mode” and “Use custom color”. Enter #66B2FF as the color to use.

    To take screenshots of specific parts of a window, the “Use interactive window capture mode” is fine.

  2. Use Windows 7 with the default theme.

  3. Ensure your PureBasic IDE is setup with the default preferences settings and color theme.

3. Code Conventions

Some code styles conventions for the code examples for the various commands. The goal is to provide end users with consistent looking code sources.

  1. Always uses a 2 spaces indent, even before the first statement:

    @Code
      If a = 10
        If b = 10
        EndIf
      EndIf
    @EndCode
  2. Don’t use types (e.g. .w, .b) unless absolutely necessary, because they make the code slightly harder to read.

    OK:
      For k = 0 To 10
    
      Next
    Wrong:
      For k.w = 0 To 10
    
      Next
  3. Insert separating spaces between parameters, operators, constants, etc.

    OK:
      If OpenWindow(0, 0, 0, 100, 100, "Test", #PB_Window_SystemMenu | #PB_MaximizeGadget)
    
      EndIf
    Wrong:
      If OpenWindow(0,0,0,100,100,"Test",#PB_Window_SystemMenu|#PB_MaximizeGadget)
    
      EndIf
  4. Don’t use the End, FreeXXX(), CloseXXX() statement unless necessary. The code is clearer without them.

    OK:
    @Code
      OpenConsole()
    
      If ReadFile(0, "C:\Test.txt")
        PrintN(ReadString())
      EndIf
    @EndCode
    Wrong:
    @Code
      OpenConsole()
    
      If ReadFile(0, "C:\Test.txt")
        PrintN(ReadString())
        CloseFile(0)
      EndIf
    
      CloseConsole()
      End
    @EndCode
  5. Variables names and other identifiers should be in camel case, not in snake case — i.e. mixed-case, without _:

    • OK: MyVariable

    • Wrong: my_variable, My_Variable

  6. Add more here if needed :p !

Contributing and Support

Feel free to contribute to this document by submitting your own fixes and improvements via Git and creating a pull request on the PureBasic Open Source repository:

If you have any questions, remarks or suggestions, just write to: <support@purebasic.com>.