Style guide for automated api.txt?

Post Reply
User avatar
SonosFuer
Member
Posts: 104
Joined: Sun Jul 09, 2017 00:32
GitHub: apachano
IRC: SonosFuer
In-game: SonosFuer

Style guide for automated api.txt?

by SonosFuer » Post

I want to propose a style guide for formatting api.txt files. I think it would be beneficial for the information to be able to be collected by a script then transferred into other resources such as collected api guides and resources for IDE's. What do you guys think?
Working on a content database for minetest mods, servers, and etc Check it out and give me feedback at viewtopic.php?f=14&t=18137

User avatar
Pyrollo
Developer
Posts: 385
Joined: Mon Jan 08, 2018 15:14
GitHub: pyrollo
In-game: Naj
Location: Paris

Re: Style guide for automated api.txt?

by Pyrollo » Post

I think it could be good to keep compatible with documentation from source code systems like those ones :

http://lua-users.org/wiki/DocumentingLuaCode
[ Display Modpack ] - [ Digiterms ] - [ Crater MG ] - [ LATE ]

User avatar
ChimneySwift
Member
Posts: 320
Joined: Fri Sep 22, 2017 06:46
GitHub: ChimneySwift
IRC: ChimneySwift
In-game: ChimneySwift
Location: 127.0.0.1

Re: Style guide for automated api.txt?

by ChimneySwift » Post

Is it just me or would it be beneficial to make it a .md file rather than a .txt file, as many text editors do syntax highlighting for markdown documents and GitHub shows them in a much easier to read format. I know I always change the file extension of files like this (eg, lua_api.txt). Obviously this is assuming they're written in markdown in the first place.
A spoon is basically a tiny bowl with a stick on it

User avatar
SonosFuer
Member
Posts: 104
Joined: Sun Jul 09, 2017 00:32
GitHub: apachano
IRC: SonosFuer
In-game: SonosFuer

Re: Style guide for automated api.txt?

by SonosFuer » Post

Structuring in markdown could be beneficial but it could also provide issues with automation. If you want to automate pulling from the api file you need a specifically structured api file, almost as if it is code itself. You could do it but I feel like it would distract from the importance of machine readability when developers are filling it out.

You could also have an automated script take from the api file and print out a well formatted md file.
Working on a content database for minetest mods, servers, and etc Check it out and give me feedback at viewtopic.php?f=14&t=18137

User avatar
rubenwardy
Moderator
Posts: 6972
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: Bristol, United Kingdom
Contact:

Re: Style guide for automated api.txt?

by rubenwardy » Post

The file is already structured in MD form, it just isn't .MD as you then can't link to lines on github
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

Post Reply

Who is online

Users browsing this forum: No registered users and 10 guests