Tworzenie dokumentacji technicznej w JavaDoc.

Question

Witam was, 

Potrzebuje pomocy w poprawnym stworzeniu dokumentacji jakie elementy i treści powinna zawierać. Dla przykładu podaje metodę z kontrolera z adnotacją stworzoną przeze mnie. Dzięki za wszystkie wskazówki.

/**
 * Method for editing the position.
 * @param id Position ID.
 * @return  success = position is edited -> view company structure/ error = view with form to edit.
 * */
@PostMapping(value = "/admin/update/position/{id}")
public String editPositionAction(@Valid @PathVariable("id") int id, PositionDto positionDto, BindingResult result, Model
        model) {
    if (result.hasErrors()) {
        model.addAttribute("departmentList", departmentService.findAllDepartamentDto());
        model.addAttribute("positionDto", positionDto);
        model.addAttribute("failedMessage", "Coś poszło nie tak !");
        return "editPosition";
    }
    if (positionService.findPositionByName(positionDto.getName()) != null) {
        model.addAttribute("departmentList", departmentService.findAllDepartamentDto());
        model.addAttribute("failedMessage", "takie stanowisko juz istnieje !!!");
        model.addAttribute("positionDto", positionDto);
        return "editPosition";
    }
    positionService.updatePosition(positionDto.getName(), positionDto.getNrDepartment(), id);
    return "redirect:/admin/companyStructure";
}

 

Answer 1

Hej! Że tak powiem "story time". Dawno dawno temu Programiści zauważyli że pisanie tego typu dokumentacji trochę mija się z celem, kod się szybko zmienia, a co w związku z tym idzie trzeba było updatować dokumentacje. Tym bardziej że jest to dokumentacja techniczna. Musi być lepszy sposób żeby to robić.

I jest. Jest narzędzie które pomaga w tworzeniu dokumentacji technicznej i jest baaardzo szeroko wykorzystywane. Nazywa się Swagger: https://swagger.io/

Pracowałem już w wielu dużych firmach (np. banki) gdzie swagger nie dość że ułatwiał życie z dokumentacją to często ratował życie :) naprawdę polecam się zapoznać z narzędziem! :)

Answer 2

Swagger to jedno, jest jeszcze coś takiego jak:

Spring REST Docs

Nie wiem czy to jest lepsze czy gorsze od swaggera, pisze czysto informacyjnie. (Nie korzystałem z tego nigdy więc nie znam szczegółów).

JavaDoc jest bardziej zdaje się do dokumentowania bibliotek czy frameworków, które wydajesz na zewnątrz. Dzięki temu masz np. opisy w podpowiedziach w IDE oraz zestandaryzowany format samej dokumentacji i nie musisz, korzystając z kolejnej biblioteki, uczyć się poruszania po niej - wchodzisz i wiesz gdzie patrzeć.