doc safety

Author: molpopgen

src/edge_table.rs

@@ -197,6 +197,13 @@ impl EdgeTable {
         Ok(Self { table_ })
     }
 
+    // # Safety
+    //
+    // * this fn must NEVER by part of the public API
+    // * all returned values must only be visible to the public API
+    //   by REFERENCE (& or &mut)
+    // * the input ptr must not be NULL
+    // * the input ptr must point to an initialized table
     pub(crate) unsafe fn new_from_table(
         edges: *mut ll_bindings::tsk_edge_table_t,
     ) -> Result<Self, TskitError> {

src/individual_table.rs

@@ -183,6 +183,13 @@ impl Iterator for IndividualTableIterator {
 }
 
 impl IndividualTable {
+    // # Safety
+    //
+    // * this fn must NEVER by part of the public API
+    // * all returned values must only be visible to the public API
+    //   by REFERENCE (& or &mut)
+    // * the input ptr must not be NULL
+    // * the input ptr must point to an initialized table
     pub(crate) unsafe fn new_from_table(
         individuals: *mut ll_bindings::tsk_individual_table_t,
     ) -> Result<Self, TskitError> {

src/migration_table.rs

@@ -211,6 +211,13 @@ pub struct MigrationTable {
 }
 
 impl MigrationTable {
+    // # Safety
+    //
+    // * this fn must NEVER by part of the public API
+    // * all returned values must only be visible to the public API
+    //   by REFERENCE (& or &mut)
+    // * the input ptr must not be NULL
+    // * the input ptr must point to an initialized table
     pub(crate) unsafe fn new_from_table(
         migrations: *mut ll_bindings::tsk_migration_table_t,
     ) -> Result<Self, TskitError> {

src/mutation_table.rs

@@ -207,6 +207,13 @@ pub struct MutationTable {
 }
 
 impl MutationTable {
+    // # Safety
+    //
+    // * this fn must NEVER by part of the public API
+    // * all returned values must only be visible to the public API
+    //   by REFERENCE (& or &mut)
+    // * the input ptr must not be NULL
+    // * the input ptr must point to an initialized table
     pub(crate) unsafe fn new_from_table(
         mutations: *mut ll_bindings::tsk_mutation_table_t,
     ) -> Result<Self, TskitError> {

src/node_table.rs

@@ -439,6 +439,13 @@ impl NodeTable {
         Ok(Self { table_ })
     }
 
+    // # Safety
+    //
+    // * this fn must NEVER by part of the public API
+    // * all returned values must only be visible to the public API
+    //   by REFERENCE (& or &mut)
+    // * the input ptr must not be NULL
+    // * the input ptr must point to an initialized table
     pub(crate) unsafe fn new_from_table(
         nodes: *mut ll_bindings::tsk_node_table_t,
     ) -> Result<Self, TskitError> {

src/population_table.rs

@@ -157,6 +157,13 @@ pub struct PopulationTable {
 }
 
 impl PopulationTable {
+    // # Safety
+    //
+    // * this fn must NEVER by part of the public API
+    // * all returned values must only be visible to the public API
+    //   by REFERENCE (& or &mut)
+    // * the input ptr must not be NULL
+    // * the input ptr must point to an initialized table
     pub(crate) unsafe fn new_from_table(
         populations: *mut ll_bindings::tsk_population_table_t,
     ) -> Result<Self, TskitError> {

src/provenance.rs

@@ -154,6 +154,13 @@ pub struct ProvenanceTable {
 }
 
 impl ProvenanceTable {
+    // # Safety
+    //
+    // * this fn must NEVER by part of the public API
+    // * all returned values must only be visible to the public API
+    //   by REFERENCE (& or &mut)
+    // * the input ptr must not be NULL
+    // * the input ptr must point to an initialized table
     pub(crate) unsafe fn new_from_table(
         provenances: *mut ll_bindings::tsk_provenance_table_t,
     ) -> Result<Self, crate::TskitError> {

src/site_table.rs

@@ -176,6 +176,13 @@ pub struct SiteTable {
 }
 
 impl SiteTable {
+    // # Safety
+    //
+    // * this fn must NEVER by part of the public API
+    // * all returned values must only be visible to the public API
+    //   by REFERENCE (& or &mut)
+    // * the input ptr must not be NULL
+    // * the input ptr must point to an initialized table
     pub(crate) unsafe fn new_from_table(
         sites: *mut ll_bindings::tsk_site_table_t,
     ) -> Result<Self, TskitError> {