mirror of
https://github.com/EsotericSoftware/spine-runtimes.git
synced 2026-02-26 03:31:24 +08:00
215 lines
12 KiB
Markdown
215 lines
12 KiB
Markdown
# Spine Godot Documentation Update Guide
|
|
|
|
## Overview
|
|
This document serves as a reusable prompt for updating the Spine Godot documentation. The documentation consists of XML files in `spine_godot/docs/` that document the user-facing API classes exposed to GDScript.
|
|
|
|
## Key Rule
|
|
**Any `SpineXXX.h` class that contains a `_bind_methods()` declaration must be documented**, as this indicates the class is exposed to GDScript users.
|
|
|
|
## Instructions for Documentation Update
|
|
|
|
**IMPORTANT: DO NOT USE TASK AGENTS FOR THIS WORK!** You must work on documentation sequentially, one class at a time, checking off completed items as you go.
|
|
|
|
### Step 1: Analyze Current State
|
|
Before updating documentation, you must:
|
|
1. Run: `grep -l "_bind_methods" spine_godot/Spine*.h | sort` to find all classes that need documentation
|
|
2. List all existing `.xml` files in `spine_godot/docs/`
|
|
3. Compare the two lists to identify missing documentation
|
|
4. Update the checklist below based on current state
|
|
|
|
### Step 2: Documentation Sources
|
|
For each class that needs documentation:
|
|
1. **Primary source**: The Godot wrapper header in `spine_godot/SpineXXX.h` - check the `_bind_methods()` implementation in the corresponding `.cpp` file to see what's exposed
|
|
2. **CRITICAL source for documentation text**: The corresponding spine-cpp header in `spine_godot/spine-cpp/include/spine/*.h` - **COPY AND ADAPT THE DOCUMENTATION FROM HERE**
|
|
3. **Implementation details**: The corresponding `.cpp` file if needed for understanding behavior
|
|
|
|
### Step 3: Update Process (WORK SEQUENTIALLY)
|
|
For each class in the checklist, working one at a time:
|
|
1. Read the wrapper's `_bind_methods()` to identify all exposed methods, properties, signals, and constants
|
|
2. **READ THE SPINE-CPP HEADER FILE AND COPY THE DOCUMENTATION COMMENTS** - Look for:
|
|
- Class-level documentation (usually after `class ClassName`)
|
|
- Method documentation (usually comments above or near methods)
|
|
- Member variable documentation (inline comments or above declarations)
|
|
3. **ADAPT the spine-cpp documentation to GDScript**:
|
|
- Convert C++ terminology to GDScript terminology
|
|
- Adjust examples to use GDScript syntax
|
|
- Keep the technical accuracy and detail from the original documentation
|
|
4. For Godot-specific additions (signals, properties not in spine-cpp), document based on implementation
|
|
5. Create or update the XML documentation following Godot's documentation format
|
|
6. Ensure all bound methods, properties, signals, and enum constants are documented
|
|
7. **Check off the item in the checklist after completing its documentation**
|
|
|
|
### CRITICAL RULE FOR DOCUMENTATION
|
|
**DO NOT WRITE GENERIC OR VAGUE DOCUMENTATION!** You must:
|
|
- Copy the actual documentation from spine-cpp headers
|
|
- Preserve technical details about what each method/property does
|
|
- Explain the purpose and behavior as documented in spine-cpp
|
|
- Only write your own documentation for Godot-specific features not in spine-cpp
|
|
|
|
## Documentation Checklist
|
|
|
|
**Instructions**: Update this checklist every time before processing documentation updates. Check the box [x] when documentation is complete and up-to-date.
|
|
|
|
### Classes with Existing Documentation
|
|
Based on files in `spine_godot/docs/`:
|
|
- [ ] **SpineAnimation** - `spine_godot/SpineAnimation.h` → `spine-cpp/include/spine/Animation.h`
|
|
- [ ] **SpineAnimationState** - `spine_godot/SpineAnimationState.h` → `spine-cpp/include/spine/AnimationState.h`
|
|
- [ ] **SpineAnimationTrack** - `spine_godot/SpineAnimationTrack.h` → (Godot wrapper specific)
|
|
- [ ] **SpineAtlasResource** - `spine_godot/SpineAtlasResource.h` → `spine-cpp/include/spine/Atlas.h`
|
|
- [ ] **SpineAttachment** - `spine_godot/SpineAttachment.h` → `spine-cpp/include/spine/Attachment.h`
|
|
- [ ] **SpineBone** - `spine_godot/SpineBone.h` → `spine-cpp/include/spine/Bone.h`
|
|
- [ ] **SpineBoneData** - `spine_godot/SpineBoneData.h` → `spine-cpp/include/spine/BoneData.h`
|
|
- [ ] **SpineBoneNode** - `spine_godot/SpineBoneNode.h` → (Godot node wrapper)
|
|
- [ ] **SpineConstraintData** - `spine_godot/SpineConstraintData.h` → `spine-cpp/include/spine/ConstraintData.h`
|
|
- [ ] **SpineEvent** - `spine_godot/SpineEvent.h` → `spine-cpp/include/spine/Event.h`
|
|
- [ ] **SpineIkConstraint** - `spine_godot/SpineIkConstraint.h` → `spine-cpp/include/spine/IkConstraint.h`
|
|
- [ ] **SpineIkConstraintData** - `spine_godot/SpineIkConstraintData.h` → `spine-cpp/include/spine/IkConstraintData.h`
|
|
- [ ] **SpinePathConstraint** - `spine_godot/SpinePathConstraint.h` → `spine-cpp/include/spine/PathConstraint.h`
|
|
- [ ] **SpinePathConstraintData** - `spine_godot/SpinePathConstraintData.h` → `spine-cpp/include/spine/PathConstraintData.h`
|
|
- [ ] **SpineSkeleton** - `spine_godot/SpineSkeleton.h` → `spine-cpp/include/spine/Skeleton.h`
|
|
- [ ] **SpineSkeletonDataResource** - `spine_godot/SpineSkeletonDataResource.h` → `spine-cpp/include/spine/SkeletonData.h`
|
|
- [ ] **SpineSkeletonFileResource** - `spine_godot/SpineSkeletonFileResource.h` → (Godot resource loader)
|
|
- [ ] **SpineSkin** - `spine_godot/SpineSkin.h` → `spine-cpp/include/spine/Skin.h`
|
|
- [ ] **SpineSlot** - `spine_godot/SpineSlot.h` → `spine-cpp/include/spine/Slot.h`
|
|
- [ ] **SpineSlotData** - `spine_godot/SpineSlotData.h` → `spine-cpp/include/spine/SlotData.h`
|
|
- [ ] **SpineSlotNode** - `spine_godot/SpineSlotNode.h` → (Godot node wrapper)
|
|
- [ ] **SpineSprite** - `spine_godot/SpineSprite.h` → (Main Godot node for Spine animations)
|
|
- [ ] **SpineTimeline** - `spine_godot/SpineTimeline.h` → `spine-cpp/include/spine/Timeline.h`
|
|
- [ ] **SpineTrackEntry** - `spine_godot/SpineTrackEntry.h` → (Part of AnimationState)
|
|
- [ ] **SpineTransformConstraint** - `spine_godot/SpineTransformConstraint.h` → `spine-cpp/include/spine/TransformConstraint.h`
|
|
- [ ] **SpineTransformConstraintData** - `spine_godot/SpineTransformConstraintData.h` → `spine-cpp/include/spine/TransformConstraintData.h`
|
|
|
|
### Classes Missing Documentation (Have _bind_methods but no .xml file)
|
|
These classes have `_bind_methods()` in their headers but lack documentation:
|
|
|
|
#### Data Classes
|
|
- [ ] **SpineEventData** - `spine_godot/SpineEventData.h` → `spine-cpp/include/spine/EventData.h`
|
|
- Setup pose data for events
|
|
|
|
#### Physics Classes (New in 4.x)
|
|
- [ ] **SpinePhysicsConstraint** - `spine_godot/SpinePhysicsConstraint.h` → `spine-cpp/include/spine/PhysicsConstraint.h`
|
|
- Runtime physics constraint
|
|
- [ ] **SpinePhysicsConstraintData** - `spine_godot/SpinePhysicsConstraintData.h` → `spine-cpp/include/spine/PhysicsConstraintData.h`
|
|
- Setup data for physics constraints
|
|
- [ ] **SpinePhysicsConstraintPose** - `spine_godot/SpinePhysicsConstraintPose.h` → `spine-cpp/include/spine/PhysicsConstraintPose.h`
|
|
- Physics constraint pose state
|
|
|
|
#### Slider Classes (New in 4.x)
|
|
- [ ] **SpineSlider** - `spine_godot/SpineSlider.h` → `spine-cpp/include/spine/Slider.h`
|
|
- Runtime slider for property animation
|
|
- [ ] **SpineSliderData** - `spine_godot/SpineSliderData.h` → `spine-cpp/include/spine/SliderData.h`
|
|
- Setup data for sliders
|
|
- [ ] **SpineSliderPose** - `spine_godot/SpineSliderPose.h` → `spine-cpp/include/spine/SliderPose.h`
|
|
- Slider pose state
|
|
|
|
#### Pose Classes
|
|
- [x] **SpineBoneLocal** - `spine_godot/SpineBoneLocal.h` → `spine-cpp/include/spine/BoneLocal.h`
|
|
- Local bone transform data
|
|
- [x] **SpineBonePose** - `spine_godot/SpineBonePose.h` → `spine-cpp/include/spine/BonePose.h`
|
|
- Bone pose state
|
|
- [ ] **SpineIkConstraintPose** - `spine_godot/SpineIkConstraintPose.h` → `spine-cpp/include/spine/IkConstraintPose.h`
|
|
- IK constraint pose state
|
|
- [ ] **SpinePathConstraintPose** - `spine_godot/SpinePathConstraintPose.h` → `spine-cpp/include/spine/PathConstraintPose.h`
|
|
- Path constraint pose state
|
|
- [ ] **SpineSlotPose** - `spine_godot/SpineSlotPose.h` → `spine-cpp/include/spine/SlotPose.h`
|
|
- Slot pose state
|
|
- [ ] **SpineTransformConstraintPose** - `spine_godot/SpineTransformConstraintPose.h` → `spine-cpp/include/spine/TransformConstraintPose.h`
|
|
- Transform constraint pose state
|
|
|
|
#### Constants/Enums Class
|
|
- [ ] **SpineConstant** - `spine_godot/SpineConstant.h` → (Godot-specific constants)
|
|
- Exposes Spine enums and constants to GDScript (MixBlend, MixDirection, Property, etc.)
|
|
|
|
### Classes to Skip (Internal/Editor Only)
|
|
These have `_bind_methods()` but should NOT have user-facing documentation:
|
|
- **SpineCommon** - Internal base classes and utilities
|
|
- **SpineEditorPlugin** - Editor-only functionality
|
|
|
|
## Documentation Template
|
|
|
|
When creating new documentation files, use this template:
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="SpineClassName" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
|
|
<brief_description>
|
|
One-line description of the class purpose.
|
|
</brief_description>
|
|
<description>
|
|
Detailed description of the class.
|
|
Include usage context and relationship to other Spine classes.
|
|
For wrapper classes, explain what Spine runtime feature this exposes.
|
|
</description>
|
|
<methods>
|
|
<method name="method_name">
|
|
<return type="return_type" />
|
|
<param index="0" name="param_name" type="param_type" />
|
|
<description>
|
|
Method description. Check _bind_methods() for exact signature.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<members>
|
|
<member name="property_name" type="property_type" setter="set_property" getter="get_property">
|
|
Property description. Must match ADD_PROPERTY in _bind_methods().
|
|
</member>
|
|
</members>
|
|
<signals>
|
|
<signal name="signal_name">
|
|
<param index="0" name="param_name" type="param_type" />
|
|
<description>
|
|
Signal description. Must match ADD_SIGNAL in _bind_methods().
|
|
</description>
|
|
</signal>
|
|
</signals>
|
|
<constants>
|
|
<constant name="CONSTANT_NAME" value="0" enum="EnumName">
|
|
Constant description. Must match BIND_ENUM_CONSTANT in _bind_methods().
|
|
</constant>
|
|
</constants>
|
|
</class>
|
|
```
|
|
|
|
## Validation Steps
|
|
|
|
After updating documentation:
|
|
1. Verify every method in `_bind_methods()` has corresponding documentation
|
|
2. Check that all `ADD_PROPERTY` calls have corresponding member documentation
|
|
3. Verify all `ADD_SIGNAL` calls have corresponding signal documentation
|
|
4. Ensure all `BIND_ENUM_CONSTANT` calls have corresponding constant documentation
|
|
5. Test that property setters/getters match the actual implementation
|
|
6. Validate that examples (if provided) are valid GDScript code
|
|
|
|
## Important Notes
|
|
|
|
### Identifying What to Document
|
|
- Run `grep -l "_bind_methods" spine_godot/Spine*.h` to get the definitive list
|
|
- The presence of `_bind_methods()` is the key indicator that a class needs documentation
|
|
- Even if a class seems internal, if it has `_bind_methods()` it's exposed to users
|
|
|
|
### Class Categories
|
|
1. **Core Runtime Classes**: SpineSkeleton, SpineAnimation, SpineBone, etc.
|
|
2. **Data Classes**: Classes ending in "Data" that hold setup/configuration
|
|
3. **Pose Classes**: Classes ending in "Pose" that represent runtime state
|
|
4. **Constraint Classes**: IK, Path, Transform, Physics constraints
|
|
5. **Resource Classes**: Atlas, SkeletonData, SkeletonFile resources
|
|
6. **Node Classes**: SpineSprite, SpineBoneNode, SpineSlotNode (Godot scene nodes)
|
|
7. **Constants Class**: SpineConstant (enum definitions)
|
|
|
|
### Version Considerations
|
|
- Physics constraints and sliders are new in Spine 4.x
|
|
- Some features may not be available in all Spine versions
|
|
- Documentation should note version requirements where applicable
|
|
|
|
## Running the Documentation Update
|
|
|
|
To use this guide:
|
|
1. Run `grep -l "_bind_methods" spine_godot/Spine*.h | sort` to get current list
|
|
2. Compare with existing .xml files in `spine_godot/docs/`
|
|
3. Update this checklist based on findings
|
|
4. For each unchecked item, create or update the XML documentation
|
|
5. Focus on the `_bind_methods()` implementation to ensure accuracy
|
|
6. Mark items as complete when documentation is finished
|
|
7. Commit with message indicating which classes were documented
|
|
|
|
Remember: The presence of `_bind_methods()` is the definitive indicator that a class needs documentation. |