Contents Menu Expand Light mode Dark mode Auto light/dark, in light mode Auto light/dark, in dark mode
Vala Documentation
Logo
Vala Documentation
  • Home
  • About
  • Installation Guide
  • Tutorials
    • GUI Programming
      • GTK4 Samples
        • Minimal App
        • Basic App
        • Synchronising Widgets
        • Text File Viewer
        • ListView
        • ListView with CheckButtons
        • ColumnView
        • Clipboard
        • Entry Completion with Two Cells
      • GNOME Developer Documenation - Tutorials
      • elementary OS - Writing Apps
    • Programming Language
      • Main Tutorial
        • 1. First Program
        • 2. Basics
          • 2.1. Source Files and Compilation
          • 2.2. Syntax Overview
          • 2.3. Comments
          • 2.4. Data Types
          • 2.5. Operators
          • 2.6. Control Structures
          • 2.7. Language Elements
          • 2.8. Code Attributes
        • 3. Object Oriented Programming
          • 3.1. Basics
          • 3.2. Construction
          • 3.3. Destruction
          • 3.4. Signals
          • 3.5. Properties
          • 3.6. Inheritance
          • 3.7. Abstract Classes
          • 3.8. Interfaces
          • 3.9. Polymorphism
          • 3.10. Method Hiding
          • 3.11. Run-Time Type Information
          • 3.12. Dynamic Type Casting
          • 3.13. Generics
          • 3.14. GObject-Style Construction
        • 4. Advanced Features
          • 4.1. Assertions and Contract Programming
          • 4.2. Error Handling
          • 4.3. Parameter Directions
          • 4.4. Collections
          • 4.5. Methods With Syntax Support
          • 4.6. Multi-Threading
          • 4.7. The Main Loop
          • 4.8. Asynchronous Methods
          • 4.9. Weak References
          • 4.10. Ownership
          • 4.11. Variable-Length Argument Lists
          • 4.12. Pointers
          • 4.13. Non-Object classes
          • 4.14. D-Bus Integration
          • 4.15. Profiles
        • 5. Experimental Features
          • 5.1. Chained Relational Expressions
          • 5.2. Regular Expression Literals
          • 5.3. Strict Non-Null Mode
        • 6. Libraries
          • 6.1. Using Libraries
          • 6.2. Creating a Library
          • 6.3. Binding Libraries with VAPI Files
          • 6.4. ABI and API Design Choices
          • 6.5. Binding to Vala Libraries from Other Languages
          • 6.6. Using Autotools
        • 7. Tools
          • 7.1. valac
          • 7.2. valadoc
          • 7.3. vapigen
          • 7.4. vala-gen-introspect
        • 8. Techniques
          • 8.1. Debugging
          • 8.2. Using GLib
  • Tooling
    • Build Systems
    • Code Editors and IDEs
    • Language Server Protocol Support
    • Other Tools
    • Syntax Support
  • Contributor Guide
    • Compiler Guide
      • 1. Project Information
      • 2. Environment Setup
      • 3. The Vala Compiler
        • 3.1. Vala in a Nutshell
        • 3.2. Parser
        • 3.3. Semantic Analyzer
        • 3.4. Symbol Resolution
        • 3.5. Flow Analyzer
        • 3.6. C Code Generation
        • 3.7. C Code Compilation and Linking
      • 4. Vala Bindings - VAPI
      • 5. libgee Internal
      • 6. Other Tools
      • 7. Testing
      • 8. Documentation
      • 9. Build System
  • Developer Guides
    • Bindings
      • Generating a VAPI with GObject Introspection
      • Why Distribute Bindings Upstream
      • Writing a VAPI Manually
        • 1. Prerequisites
        • 2. Getting Started
          • 2.1. The VAPI File
          • 2.2. Attribution and License
          • 2.3. The CCode Attribute
          • 2.4. Create a Root Namespace
          • 2.5. Include the C Header Files
          • 2.6. Symbol Name Translations
          • 2.7. Code Formatting Conventions
          • 2.8. Documentation and Valadoc.org
          • 2.9. The Version Attribute
        • 3. Using Vala’s Automatic Memory Management
          • 3.1. Pointers in C (or what all these *’s mean)
          • 3.2. Constants, the Stack and the Heap in C
          • 3.3. The Concept of “Ownership” in Vala
          • 3.4. Binding to C Heap Handlers
        • 4. Recognizing Vala Semantics in C Code
          • 4.1. Constants
          • 4.2. Enums and Flags
          • 4.3. Simple Type Structs
          • 4.4. Structs
          • 4.5. Compact Classes
          • 4.6. Functions
          • 4.7. Delegates
        • 5. Fundamentals of Binding a C Function
          • 5.1. Out and Reference Parameters and Return Values
          • 5.2. Ownership
          • 5.3. Nullability
          • 5.4. Static Methods
          • 5.5. Changing the Position of Generated Arguments
          • 5.6. Default Values and Changing an Argument’s Position
          • 5.7. Adapting a Signature with a Vala Wrapper
          • 5.8. Variadic Arguments (a.k.a. “…”)
          • 5.9. Functions That Do Not Return
          • 5.10. Methods that Change the Instance Reference
          • 5.11. Methods that Destroy the Instance Reference
        • 6. Adding Vala Friendly Semantics
          • 6.1. to_string () Methods
          • 6.2. Properties
          • 6.3. Collections
        • 7. Binding a C Function’s Parameter and Return Types
          • 7.1. Basic Types
          • 7.2. Structs
          • 7.3. Arrays
          • 7.4. Strings and Buffers
          • 7.5. Function Pointers
          • 7.6. Parameters of Variable Type (Generics)
          • 7.7. Pointers
        • 8. Binding a C Struct’s Fields
          • 8.1. Structs
          • 8.2. Pointers to Structs
          • 8.3. Arrays
          • 8.4. Function Pointers
          • 8.5. Unions
        • 9. Extra Hints
        • 10. Awkward Situations
          • 10.1. Array Lengths
          • 10.2. Dependently Typed Ownership
          • 10.3. Member Length
          • 10.4. Owned Array of Unowned Objects
          • 10.5. Shared Context Delegates
    • Documentation
      • Valadoc Guide
        • 1. Quick Start
        • 2. Command Line Tool
        • 3. Documentation Comment Markup
          • 3.1.1. Brief Description
          • 3.1.2. Formatting
          • 3.1.3. Taglets
          • 3.1.4. Contributing to Valadoc
  • FAQ
Back to top
Edit this page

3. Documentation Comment Markup¶

3.1. Documentation Comment Structure¶

/**
 * [brief description]
 *
 * [long description]
 *
 * [taglets]
 */

Note

When no comments are present, Valadoc will only extract symbols to use in the documentation.

In this chapter, we’ll explain how to fill each section of a documentation comment.

  • 3.1.1. Brief Description
  • 3.1.2. Formatting
  • 3.1.3. Taglets
  • 3.1.4. Contributing to Valadoc
Next
3.1.1. Brief Description
Previous
2. Command Line Tool
On this page
  • 3. Documentation Comment Markup
    • 3.1. Documentation Comment Structure