www.digitalmars.com         C & C++   DMDScript  

digitalmars.dip.ideas - DDoc

reply Guillaume Piolat <first.name gmail.com> writes:
I've seen that fake DDoc section in the wild:

```d
/**

      ...Inside DDoc...

      Params:
           blah = Help for blah.

      Memorysafety:
         This function does X and Y and that's why it's system.
         Here is what the caller should do to make it memory-safe,
         as in ` safe`.
*/
void myFunction(int blah){}
```


Indeed any-time I enter ` system` or an incorrect ` trusted` I 
add a comment to characterize the memory hazard.

I think we need an annotation for that!
Aug 23
parent Petar Kirov [ZombineDev] <petar.p.kirov gmail.com> writes:
On Sunday, 23 August 2026 at 09:40:51 UTC, Guillaume Piolat wrote:

 I've seen that fake DDoc section in the wild:

 ```d
 /**

      ...Inside DDoc...

      Params:
           blah = Help for blah.

      Memorysafety:
         This function does X and Y and that's why it's system.
         Here is what the caller should do to make it 
 memory-safe,
         as in ` safe`.
 */
 void myFunction(int blah){}
 ```


 Indeed any-time I enter ` system` or an incorrect ` trusted` I 
 add a comment to characterize the memory hazard.

 I think we need an annotation for that!


I agree we should have codify a convention like that, tnx for 
bringing it up! For reference, there is a similar one in Rust:
https://rust-lang.github.io/api-guidelines/documentation.html#function-docs-include-error-panic-and-safety-considerations-c-failure

and even a linter rule so that you can enforce it in your 
codebase:

https://rust-lang.github.io/rust-clippy/master/index.html?search=missing_safety_doc#missing_safety_doc
Aug 23