

Ask HN: Automatic generation of code documentation - botbot

Hi HN,<p>I am a religious follower of DRY (Don&#x27;t repeat yourself).<p>In my line of work, I tend to use modelling tools (eg. UML) in order to plan out and structure my code. Once the modelling has been done, I create, test and implement the program (with comments). Once the program is in place for its intended purpose, I document the code to the end-user.<p>My question is about automatic generation of code and&#x2F;or documentation. It seems to me that whichever task in my workflow I choose, it is a 1 way mapping.<p>ie.
Model -&gt; Code<p>Code -&gt; Model<p>Code -&gt; Documentation<p>Documentation -&gt; Code<p>So if I change my code, I then have to update my model as well as my end-user documentation.<p>There are ways I can automate model generation, but I am generally at the whims of the modelling environment when it comes to model regeneration from code. As well as this, generating code from the model and generating the model from the code seem to be two different, complex problems all on their own.<p>I can generate code from my model, but sometimes it is not feasible to regenerate code from a model due to code modifications that occur when the code is actually deployed.<p>How do you guys handle these activities?
======
twunde
I typically will generate basic code from a model and then after I make
modifications I regenerate documentation and the model. To make a 2-way
mapping really work you for you would have to separate generated code from
code that you modify.

~~~
botbot
this is something I will consider, thanks for your idea

------
KNoureen
I guess that depends on your toolchain.

For Java, I use Maven which have some powerful tools (Maven Site) to create
test-reports, documentation, api-docs, coverage reports, diagrams and much
more. It's also easy to extend yourself.

------
Seb86
A great tool is Swagger, very useful is your app has a REST API as a back-end.

