doc: clarify when manual struct edits are allowed

1 files changed, 12 insertions, 0 deletions

diff --git a/libass/ass.h b/libass/ass.h
index c7ff8d9..5044081 100644
--- a/libass/ass.h
+++ b/libass/ass.h
@@ -627,6 +627,7 @@ void ass_free_track(ASS_Track *track);
  * \brief Allocate new style.
  * \param track track
  * \return newly allocated style id >= 0, or a value < 0 on failure
+ * See GENERAL NOTE in ass_types.h.
  */
 int ass_alloc_style(ASS_Track *track);
 
@@ -634,6 +635,7 @@ int ass_alloc_style(ASS_Track *track);
  * \brief Allocate new event.
  * \param track track
  * \return newly allocated event id >= 0, or a value < 0 on failure
+ * See GENERAL NOTE in ass_types.h.
  */
 int ass_alloc_event(ASS_Track *track);
 
@@ -642,6 +644,12 @@ int ass_alloc_event(ASS_Track *track);
  * \param track track
  * \param sid style id
  * Deallocates style data. Does not modify track->n_styles.
+ * Freeing a style without subsequently setting track->n_styles
+ * to a value less than or equal to the freed style id before calling
+ * any other libass API function on the track is undefined behaviour.
+ * Additionally a freed style style still being referenced by an event
+ * in track->events will also result in undefined behaviour.
+ * See GENERAL NOTE in ass_types.h.
  */
 void ass_free_style(ASS_Track *track, int sid);
 
@@ -650,6 +658,10 @@ void ass_free_style(ASS_Track *track, int sid);
  * \param track track
  * \param eid event id
  * Deallocates event data. Does not modify track->n_events.
+ * Freeing an event without subsequently setting track->n_events
+ * to a value less than or equal to the freed event id before calling
+ * any other libass API function on the track is undefined behaviour.
+ * See GENERAL NOTE in ass_types.h
  */
 void ass_free_event(ASS_Track *track, int eid);