Re: PL/SQL Comment Parser
Date: Fri, 30 Jan 2015 23:09:12 -0600
Message-ID: <CAMNhnU0XxmoT+c7QP05WXvB8TCEjoHB9s04E7+i0Q5-bqdk8QQ_at_mail.gmail.com>
Well here is the first cut of the comment parser. Amazing how many little things you find to fix as soon as you think you are ready to share :)
https://github.com/ethanpost/GO
I am going to add a bunch of other stuff to the package (some string functions already added) over time but the doc_to_markdown procedure is the focus for now. The go_doc.pdf file was created by getting parsing the docs using doc_to_markdown procedure and then uploading to stackedit.io.
Plenty of bugs and not totally PLDOC compatible but a start but it is working for me.
Thanks,
EP
On Thu, Jan 15, 2015 at 2:39 PM, Ethan Post <post.ethan_at_gmail.com> wrote:
> I am throwing together a PL/SQL comment parser and will share it when I am
> done. Not going to put too much into this and don't want to over think it
> but wanted to share here and if you have any suggestions let me know and
> maybe I can incorporate them.
>
> I have looked at PLDOC and it isn't quite what I need.
>
> I am trying to adhere to the PLDOC/JAVADOC format to some degree in case I
> end up wanting to use that in the future.
>
> This is going to be a procedure which parses USER_SOURCE and puts the
> comments in a table (better than a separate java program IMO). Once that is
> all working I will write a parser which puts it all in Markdown I think.
> For now my goal is to get the parsing procedure built and get the data into
> a table. The final outputs will come later. Ideally everything will live in
> the database and the outputs can be viewed using a SELECT statement.
>
> Some of the tags below require a bit more explanation.
>
> _at_user is meant for the end user of a product, in this case a PLSQL
> framework which is written by me but occasionally used by many technical
> staff. These folks need docs but not dev type docs. I have found it
> impossible to maintain any type of docs outside the product for a number of
> reasons. Keeping all docs inline with code is maintainable and will keep
> the managers off my back when they ask for docs who are looking more for
> information on capabilities and features, which for this code base will
> still work to keep with the PLSQL.
>
> _at_feature is meant to express a feature of the program. For example
> moon_phase procedure might be a good place to store the comment "We monitor
> all phases of the moon.". This can be handed off to the sales dept to help
> promote the benefits of the program and you get an easy way to maintain
> this list.
>
> Here is the format I am current working on parsing.
>
> function is_sql_hot (p_foo_var number) returns number is
> begin
> /* Short bit of text about what the procedure or function does.
>
> Detailed text here is optional and you can use any format here you want
> and
> it can go on and on
> and on
>
> _at_parm P_FOO_VAR The number of times you added more commits to your
> code to prevent snapshot too old errors.
> _at_return Returns 0 if you admit we have all done it at least
> once and 1 if you are lying.
> _at_throws Error handlers? I don't need no stinkin error
> handler.
> _at_user Hot SQL is saved in the HOT_SQL_REPO table which is
> better than TMI_SQL_HIST.
> _at_fyi Do you know how to find the latest about hot sql?
> _at_feature Our program frequently monitors the Hottest SQL!
> _at_todo Figure out what Hot SQL means.
> _at_tag Performance Monitoring, SQL
> */
> null;
> end;
> /
>
> Thanks,
> Ethan
>
-- http://www.freelists.org/webpage/oracle-lReceived on Sat Jan 31 2015 - 06:09:12 CET