https://linen.dev logo
Powered by
# haxe-ui
  • b
    Like 40 lines
  • b
    if often thought about having sometype of system where you have a seperate doc file for a class "MyClass.doc" that would have all the docs for that class, but inevitably they would end up drifting apart
  • b
    maybe haxe should adopt a 
    #if _MARKDOWN_
    kind of doc embedding
  • b
    It would be he'll for writers who also describe what the function is doing
  • b
    It already has markdown automatically
  • b
    how would that work? I mean, the docs would still be in the source files, right?
  • b
    woah ... where did i miss on that ?
  • b
    Haxe does support markdown to html & markdown docs. My goal with supporting markdown is giving that to frameworks
  • b
    my pet peeve is where you have these massive comments all over a source file explaining the source... but as i said, its a "me" thing... im pretty sure most people prefer it
  • b
    I don't really like it when it's inline too
  • b
    Just kinda obnoxious, just write understandable code
  • b
  • b
    ☝️ this type of stuff
  • b
    I think they just copied flash docs
  • b
    So that doesnt really count
  • b
    ok ... have not encountered that .. but then haxe is only a week old for me.
  • b
    That's only openfl
  • b
    im not assigning blame, im simply using it as an example, i think that example would be the "ideal" for most people, but personally i hate it since i read code far more than i do docs (i used openfl because i know they have these type of complete docs)
  • b
    but this is what i mean about having a ".doc" counterpart that doesnt intefere with the source code
  • b
    but again, they would drift apart eventually
  • b
    maybe haxe doc tool should honor a 
    <class>.md
    file right beside the `.hx`file and concateneted that to the class docs
  • b
    how would you deal with the drift?
  • b
    it can happen with "inline docs" too, but far more likely with separate files
  • b
    yeh the old "inline vs extra" code docs problem
  • b
    haxeui solves this issue with the "no docs" approach 😄
  • b
    Not for long 🥴
  • b
    haha
  • b
    so once i get RSI from scrolling pages and pages of "source code", i can sue you? :-p
  • b
    i have written a custom class generator for DAOs that will also automatically extract markdown basically i resorted to a preprocessor style 
    #if _MARKDOWN_ #endif
    solution
  • b
    Because it's not my code I'll probably write shorter docs
1...100310041005...1687Latest