[Bro-Dev] [JIRA] (BIT-1098) topic/jsiwek/broxygen

[Robin Sommer (JIRA)]

    [ https://bro-tracker.atlassian.net/browse/BIT-1098?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14906#comment-14906 ] 

Robin Sommer commented on BIT-1098:
-----------------------------------

Excellent, I like the new way of feeding the Broxygen manager. 

I've merged it. Some additional suggestions:

- what would you think about moving the global type alias table into BroType as a private static member,  along with a few static accessor methods to manipulate it?
- if there's a bro binary in PATH, it seems that "make doc" picks up that one instead of the one in {{src/build/bro}}
- "make doc" shows {{received termination signal}} right before {{Running Sphinx}}. Is that expected?

- reST Output:
-- I'd remove the "Param" in the function descriptions (or is that a Sphinx thing?)
-- If a package has scripts both w/ and wo/ a further description, they appear separately in the package overview; see, e.g., {{scripts/base/frameworks/packet-filter/index.html}}
-- should we just omit {{__load__.bro}} in the package overviews?
-- I like how the records now show fields that are redefined somewhere else. Two further thoughts: 
--- how about changing {{from redef in XXX}} to {{added if XXX is loaded}}. For a user, it might be more intuitive to talk about loading another script than just redef.
--- for the script that does the redef, can we show the new fields there as well? For example, in {{scripts/policy/protocols/http/software-browser-plugins.bro.html}} it would show not only that {{HTTP::Info}} got redef, but also repeat the fields it added right there. Same for the enums. 






> topic/jsiwek/broxygen
> ---------------------
>
>                 Key: BIT-1098
>                 URL: https://bro-tracker.atlassian.net/browse/BIT-1098
>             Project: Bro Issue Tracker
>          Issue Type: Improvement
>          Components: Bro, Broccoli
>    Affects Versions: git/master
>            Reporter: Jon Siwek
>             Fix For: 2.3
>
>
> This branch is in the bro and broccoli repos and improves the automated script-reference documentation generation process, broxygen.
> This should address issues in BIT-701 and BIT-751, let me know if there's anything not covered that's still relevant.
> Highlights:
> - Remove {{--doc-scripts}} and {{-Z}} options to toggle documentation mode -- the parser is now always instrumented to gather documentation from comments of the form "##", "##!", or "##<".
> - Raw comments are available at runtime through several BIF functions: {{get_*_comments}};
> - Add {{--broxygen}} and {{-X}} options to toggle generating reST-format documentation output, driven by a config file argument.
> - Add a "broxygen" Sphinx extension domain, allowing certain pieces of documentation to be generated on-the-fly via invoking a Bro process.  Re-organized/cleaned up the Sphinx source tree in {{doc/}} to use this in some places.



--
This message was sent by Atlassian JIRA
(v6.2-OD-03#6206)